Remote agents and CI

Run Ploy where no browser or persistent local CLI session is available.

Environment	Use it for	Typical state
Claude Cowork or another remote coding agent	Editing, testing, and pushing a Code Sync repository	A checked-out repository that may persist between sessions
CI	Repeatable checks and non-interactive Ploy commands	A fresh runner with no saved workspace or site

Before you start

Install the Ploy CLI in the remote environment.
Create an API token in workspace Settings → Developer → API tokens.
Record the workspace and site IDs your automation is allowed to use.
For code changes, initialize Code Sync before handing the repository to a remote agent.

Use a separate token for each remote agent or CI environment. This makes rotation and revocation predictable when a job is retired or a key leaks.

Allow outbound access to https://ploy.ai in the container or runner's egress settings. Claude Cowork and other restricted remote environments may block Ploy CLI authentication and API requests until this domain is allowlisted.

Authenticate without a browser

Remote environments cannot complete ploy login. Provide the workspace-scoped token through the environment instead:

export PLOY_API_TOKEN=sk_ploy_pat_...
export PLOY_NO_UPDATE_CHECK=1
ploy whoami

PLOY_API_TOKEN is read on every invocation and is never written to disk. Do not paste it into an agent prompt, command argument, repository file, or build log. Store it with the remote platform's secret manager.

The token takes precedence over stored login credentials and pins access to one workspace. See Headless authentication for expiry, precedence, restricted commands, and failure behavior.

Use a remote coding agent

Give the agent the Code Sync repository, then install Ploy's skills and inspect the site's native design system before making changes:

git clone https://github.com/<owner>/<repo>.git
cd <repo>
ploy skills init
ploy design-system get-theme-colors
ploy design-system list-pages

The local design-system commands read the checkout and do not require CLI authentication. The agent should follow the installed skills, reuse registered components, run the repository's checks, and push reviewed changes to GitHub main.

After the push, import the commit through Code Sync and review the site in Ploy before publishing. Site-scoped CLI commands require a selected site; do not assume a fresh remote environment already has one.

Run non-interactive CI commands

Prefer commands that accept explicit IDs and machine-readable output. This example checks authentication and reads site status without relying on an interactive selector:

export PLOY_API_TOKEN="$PLOY_API_TOKEN"
export PLOY_NO_UPDATE_CHECK=1

ploy whoami
ploy --workspace "$PLOY_WORKSPACE_ID" site status \
  --id "$PLOY_SITE_ID" \
  --json

If PLOY_WORKSPACE_ID does not match the token's workspace pin, the API rejects the request with exit code 1. Keep IDs in CI variables and the token in secrets.

Selected sites on fresh runners

ploy site publish, ploy variable set, and ploy site code-sync sync use the site saved in CLI config. A fresh runner has no saved selection, and the token's workspace pin does not select a site.

Establish and verify workspace and site selection before adding a site-scoped mutation to CI. Do not treat a successful ploy whoami as proof that a site is selected.

Design jobs for automation

Concern	Guidance
Secrets	Mask `PLOY_API_TOKEN` and never echo the environment.
Output	Use `--json` where supported and keep stdout available for machine parsing.
Retries	Retry rate limits and transient API failures. Do not retry authentication failures.
Rate limit	Stay below 60 requests per minute for each API token.
Rotation	Check remaining lifetime with `ploy whoami` and replace the secret before expiry.
Revocation	Manage API tokens in workspace Settings → Developer, not with CLI credential commands.

Troubleshooting

Problem	What to check
`PLOY_API_TOKEN is invalid or expired`	Create a replacement token and update the remote secret. The CLI does not refresh API tokens.
`This API token is scoped to a different workspace`	Remove the conflicting workspace override or use a token created in the requested workspace.
No selected site	Remember that ephemeral runners do not inherit `~/.config/ploy/config.json`.
Exit code `2` from a credential command	`logout`, `tokens`, and `token revoke` are unavailable under `PLOY_API_TOKEN`.
Rate limited	Honor the retry delay and reduce polling or parallel CLI invocations.

Keep going

Manage CLI authentication and API tokens.
Manage workspaces, sites, publishing, and Code Sync.
Check the complete CLI contract for options, environment variables, and exit codes.