Cloud Agents

Use this setup when fp runs somewhere that cannot access the local fp store, such as a cloud coding environment, a CI job, or a fresh remote checkout. If the agent runs on your machine, you do not need FP_REMOTE or FP_TOKEN.

In remote mode, issue and comment commands talk to a shared fp project over HTTPS. There is no local database to copy into the remote environment.

Link the project

Run this once from a local checkout:

fp auth login
fp project link

Choose or create a project when prompted. fp project link writes .fp/remote.toml and makes that file available to Git:

git add .fp/remote.toml .gitignore
git commit -m "Configure fp remote project"

The file contains the workspace slug, project ID, server URL, and display prefix. It does not contain a token.

If the project was linked before remote.toml was introduced, create it with:

fp project remote stamp

Run fp project remote to check the configured project.

Create an agent token

A workspace admin or owner can create a dedicated agent and token:

fp workspace agent create \
  --workspace <workspace-slug> \
  --name <agent-name> \
  --role member \
  --expires-in 30

Workspace agent authentication must be enabled for the workspace. fp displays the token once, so copy it directly to the secret store used by the remote environment.

A personal access token also works, but a dedicated agent token is easier to revoke and does not use a person’s identity.

Configure the remote environment

Set both variables in the cloud environment or CI job:

export FP_REMOTE=rest-api
export FP_TOKEN=<token>

Do not add FP_TOKEN to .fp/remote.toml, an agent instruction file, or any other file in the repository.

Use fp from the cloud environment

After cloning the repository and installing fp, use the familiar issue and comment commands:

fp issue list
fp issue show FP-abcd
fp issue create --title "Investigate failing build"
fp issue update --status in-progress FP-abcd
fp comment FP-abcd "Reproduced in the cloud sandbox"
fp search "failing build"

REST mode supports these commands:

• fp issue list, show, create, update, delete, and assign
• fp comment add, list, update, and delete
• fp search
• fp attach

fp tree, fp context, brainstorms, and project sync still require local fp state. In REST mode, fp reports that these commands are unsupported.

Configure identity without committing a file

If the checkout does not include .fp/remote.toml, set the project identity in the environment:

export FP_REMOTE=rest-api
export FP_WORKSPACE=<workspace-slug>
export FP_PROJECT_ID=<project-id>
export FP_SERVER_URL=https://app.fp.dev
export FP_TOKEN=<token>

These values override .fp/remote.toml. Always set FP_SERVER_URL explicitly when using a server other than https://app.fp.dev.

Return to local mode

Unset the remote variables to use the local fp store again:

unset FP_REMOTE
unset FP_TOKEN