Machine commands

The polaris commands on every Machine, the tools Machines come with, and how to write setup scripts.

Every Machine has a polaris command that connects it to Polaris: it opens Previews, shares screenshots, gives commands your variables, keeps long jobs running and gets cloud credentials. The agent already knows these commands and runs them when you ask, so you rarely need them yourself. Use this page to run one in the Terminal, to write setup scripts, or to see what you can ask the agent for.

Some commands act for a Session, so they work only in the agent’s shell and refuse in a Terminal you open: polaris port (except url and logs), polaris services start, polaris share, polaris feedback, polaris notify and polaris session. Ask the agent to run those.

Run polaris --help on a Machine to list its commands. If a Machine doesn’t know a command on this page, start a new Session to get a new Machine. The CLI on your own computer is a different tool; see Polaris CLI.

Previews

• The server must listen on 0.0.0.0. Make it fail rather than move to another port if the port is taken, for example with Vite’s --strictPort.
• A kept-running server gets the Project’s variables, PORT set to its port and POLARIS_PREVIEW_ORIGIN set to its Preview link. Use the link where your app writes its own address, such as an OAuth redirect.
• To change a kept-running server’s command, retire the port first.

Share images and videos

polaris share <path>

Polaris checks the file, then prints a public link, markdown to paste into a pull request or issue, and when the file expires. If it says the file is still processing, run polaris share --status <file id> <attempt id> with the IDs it printed. Shared files also appear in the Session’s Artifacts tab.

Anyone with the link can open the file without signing in, so don’t share anything that shows secrets or private data. Organization admins turn sharing on or off and choose how long files are kept (Keep files for, 1 year by default) in Settings → General → Shared files. Turning sharing off stops existing links from working.

Common messages:

• this file type isn't supported: share a PNG, JPEG, GIF, WebP, MP4 or WebM.
• this video format isn't supported: export it again as MP4 (H.264) or WebM (VP9).
• sharing is turned off for this organization: ask an organization admin to turn it on.
• this organization reached today's 1 GB sharing limit: try again after midnight UTC, or share a smaller file.

Environment variables

The agent’s own shell and Terminal shells don’t get the Project’s variables on their own. Start a command with polaris env run -- to give it them:

polaris env run -- pnpm test:integration

Each command gets the current values when it starts; a command that is already running keeps the values it started with. A key kept off the Machine arrives as a placeholder, and Polaris adds the real key when the request leaves the Machine.

Workspace setup

polaris setup status prints one line per script:

Project setup script: absent
.agents/setup: succeeded
.agents/resume: succeeded
setup mode: the first Turn does not wait for setup

Logs hide known secret values and keep the first 5 MB of output. Each resume run replaces the previous resume log.

When scripts run

Polaris never runs setup again on the same Machine, not even after a failure. Scripts have no time limit, but Polaris keeps the Machine awake for setup for only 60 minutes, so keep setup well under an hour.

Writing setup scripts

• Start with a shebang, such as #!/usr/bin/env bash, followed by set -euo pipefail.

• Make each script safe to run twice. Check what is already installed or running before you change it, and test it twice from the repository root.

• Expect a short PATH. Scripts run from the repository root as your Machine user, with no terminal and no input. PATH is /usr/local/polaris/bin:/usr/local/bin:/usr/bin:/bin, so call a tool installed elsewhere, such as under ~/.local/bin, by its full path.

• sudo works on most Machines. Use it to install system packages. On some Machines sudo asks for a password, so a script that needs it fails there; keep that setup in user space, or start a new Session to get a new Machine.

• Commit the executable bit. A script without it fails with Not executable.

  chmod +x .agents/setup .agents/resume
  git add .agents/setup .agents/resume

• Keep secrets out of setup. The Project setup script and .agents/setup get no Project variables. Sign in to registries and start tunnels in .agents/resume, which gets them. If the variables can’t be loaded, resume doesn’t run and shows Project variables unavailable.

• Install in setup, start services in resume. Processes that setup leaves running stop when it ends. Processes that resume starts keep running, so send their output to their own log file, for example nohup node worker.js > "$HOME/worker.log" 2>&1 &. Don’t install dependencies in resume.

• Run a script by hand only when it isn’t running. Check with polaris setup status first. To run resume with the Project’s variables, run polaris env run -- .agents/resume from the repository root.

Keep a command running

The agent ends its Turn while waiting for work outside the Machine, such as a review or deployment. Where available, check-ins let it return later. Keep-awake holds are for commands running on the Machine.

The Machine stays awake while the agent works or waits on a command. A command left running in the background with nobody waiting for it doesn’t keep the Machine awake, so it pauses when the Machine sleeps. To keep the Machine awake until a long job finishes:

polaris keep-awake run -- pnpm test:e2e
polaris keep-awake run --for 2h -- python train.py

Keep the job in the foreground inside keep-awake run: when it exits, the hold ends. If the hold isn’t confirmed, the command doesn’t start.

Cloud access

These commands use the services an admin connected in Cloud access. No long-lived cloud key is stored on the Machine.

Check Tailscale

If the Machine hasn’t joined or the command can’t read status, see Tailscale setup and troubleshooting.

Use an AWS profile

Each AWS role assigned to the Project is an AWS profile on its Machines, such as polaris-logs-reader. Choose it with --profile or AWS_PROFILE. Polaris profiles set no region, so pass --region or set AWS_REGION:

aws sts get-caller-identity --profile polaris-logs-reader --region eu-west-1
AWS_PROFILE=polaris-logs-reader AWS_REGION=eu-west-1 aws sts get-caller-identity

• Credentials renew on their own; there is nothing to sign in to or rotate.
• Polaris rewrites the part of ~/.aws/config between # BEGIN POLARIS MANAGED CLOUD ACCESS PROFILES and # END POLARIS MANAGED CLOUD ACCESS PROFILES. Keep your own profiles outside it. If you define a profile with the same name, yours wins.
• The profiles get credentials from polaris aws credentials. You don’t run it yourself.

Request access to a role that needs approval

polaris access request polaris-admin --for 30m --reason "Delete the old staging stack" --wait

• --for takes a whole number followed by s, m or h, up to 24h. A request above the role’s Longest approval asks for that limit and tells you the duration it requested.
• On current CLIs, --wait returns within about 90 seconds. Older CLIs can wait longer. Approval exits with code 0 and prints the approval end time, duration, approver and profile to use. Denial, cancellation, invalidation or expiry exits nonzero with its reason. Without --wait, the command returns as soon as it sends the request. If a Machine’s polaris rejects --wait, run the command without it. If a request is already waiting for the same role, the command tells you when it was sent; its duration and reason stay unchanged.
• Requesting an active role asks for an extension. Approval starts a fresh window from the approval time; it does not add time to the old window.
• At the wait limit, the command prints the exact command to check it: polaris access status <grantId>. Status prints whether that request is pending, approved (with its end time) or ended. Reaching the wait limit leaves the request open until the printed approval deadline.
• Use the profile name shown in the Machine’s Cloud access notes. Those notes include the role’s limit. When access ends, the next AWS call prints a new request command using that profile and its current limit.
• Ask from a Session: the request appears in its transcript, where approvers decide. A request from a shell Polaris can’t match to a Session appears in no transcript.

Get an identity token

polaris id-token --audience https://vault.example.com

The command prints only the token, for a service connected as Other service. A token is valid for 5 minutes, so get a new one each time instead of saving it. An audience isn’t a secret: every Machine in your organization can get a token for every connected service, so have the service also check the Project or Machine in the token.

Tokens are signed with RS256. Services find the keys at https://plrs.sh/oidc/org/<org id>/.well-known/openid-configuration. Each token has these claims:

To find the IDs, look at addresses in Polaris. A Session’s address has the form https://plrs.sh/workspaces/<Machine id>/sessions/…?orgId=<org id>. The address of a Project’s page in Settings → Projects contains its ID, which starts with project_. A Machine keeps its ID when it sleeps and wakes.

What an AWS role trusts

A role that Polaris sets up trusts only tokens from your organization’s issuer, https://plrs.sh/oidc/org/<org id>, with the audience sts.amazonaws.com and the subject for that one role:

Polaris checks the role’s Projects, and any approval, each time it issues a token. Tokens from polaris id-token can’t assume these roles. In CloudTrail, each session’s source identity, m- followed by 32 characters, identifies the Machine.

Report a problem

polaris feedback draft < report.json

Drafts a report about Polaris from a JSON file. The draft waits in the Session until you review and send it; see Report a problem. Run polaris feedback --help for the fields.

CI notifications

Common messages:

• CI notification armed for <commit>; deadline <time>. End your Turn to wait.: Polaris sends the result for that commit when the checks finish.
• CI result already sent for <commit>. No new notification armed.: Polaris already sent the result for that commit. Push a new commit to get a new one.
• CI notification not armed (not_linked); reconnect GitHub in Polaris.: the Session owner’s GitHub account isn’t connected. They connect GitHub, then the agent runs the command again.
• CI notification not armed (reauthorization_required); reconnect GitHub in Polaris.: the Session owner’s GitHub sign-in expired. They select Reconnect GitHub; see Troubleshooting.
• CI notification not armed (...); try again shortly. or CI notification was not confirmed; retry.: Polaris couldn’t arm it right now. The agent runs the command again.

Session

The agent snoozes a Session only when you ask it to.

Desktop

Docker

Docker isn’t preinstalled. When you ask the agent to add it to Workspace setup, it uses this tested script, which keeps Docker’s images, containers and volumes on the same disk as your code. It then starts Docker and your containers again each time the Machine wakes. Docker needs root on the Machine; where a Machine doesn’t allow it, the agent tells you.

#!/usr/bin/env bash
set -euo pipefail

mountpoint -q /opt/polaris/workload

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
printf '%s\n' 'deb [signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian bookworm stable' |
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo install -d /etc/docker /etc/containerd /opt/polaris/workload/docker /opt/polaris/workload/containerd
if ! sudo test -e /etc/containerd/config.toml; then
  printf '%s\n' 'version = 2' 'root = "/opt/polaris/workload/containerd"' 'disabled_plugins = ["io.containerd.grpc.v1.cri"]' |
    sudo tee /etc/containerd/config.toml > /dev/null
fi
for service in containerd docker; do
  sudo install -d "/etc/systemd/system/$service.service.d"
  printf '%s\n' '[Unit]' 'ConditionPathIsMountPoint=/opt/polaris/workload' |
    sudo tee "/etc/systemd/system/$service.service.d/project-disk.conf" > /dev/null
done
sudo systemctl daemon-reload
if ! sudo test -e /etc/docker/daemon.json; then
  printf '%s\n' '{"data-root":"/opt/polaris/workload/docker"}' |
    sudo tee /etc/docker/daemon.json > /dev/null
fi
sudo apt-get update
sudo apt-get install -y --no-upgrade -o Dpkg::Options::=--force-confold \
  docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl enable --now docker

Preinstalled tools

Every Machine runs Debian 12 with these tools installed, so you and the agent use the same versions. A Machine keeps the versions it started with.

Machines also have Chromium, which the agent uses for the Browser. git and gh act as you on GitHub; see GitHub. Docker isn’t preinstalled; see Docker. For anything else, ask the agent to install it, and to add it to your setup if every new Machine should have it.