Cloud agents

Cloud agents run in temporary containers. To connect one to Mossbear, give the container a CLI token, install Mossbear when the container starts, and allow it to reach your dashboard.

Create a token

This is the part that differs from setup on your laptop. A cloud container cannot open a browser and complete mossbear login, so it needs a token in an environment variable.

1. Open Machines in the Mossbear dashboard.
2. Under Add a machine, enter a name for the environment, such as Claude cloud or Codex cloud.
3. Select Create token.
4. Copy the token now. Mossbear will not show it again.
5. In your cloud agent’s settings, add it as:

MOSSBEAR_TOKEN=your-token

Do not put the token in your repository or setup script. It grants access to your Mossbear account. Use a separate token for each cloud environment so you can revoke one without disconnecting your other machines.

Tip

On a laptop, use mossbear login instead. The environment variable is for containers and CI jobs that cannot complete browser login.

Configure your cloud agent

Choose the service you use.

Claude Code on the web

1. Open the environment

At claude.ai/code, open the environment selector. Create an environment, or open the settings for an existing one.

2. Add the token

Add MOSSBEAR_TOKEN to Environment variables. Paste only the token value after =. Do not add quotes.

Claude can read ordinary environment variables. Create a token just for this environment and disconnect it from Machines when you no longer use it.

3. Allow the dashboard

Set network access to Custom and add:

app.mossbear.io

Keep Also include default list of common package managers enabled so npm remains available.

4. Add the setup script

Paste this into Setup script, including the #!/bin/bash first line:

#!/bin/bash
npm install -g mossbear
mossbear init --no-prompt --platform claude_code --pull-guides || true
mossbear doctor || true

init adds the Claude Code hooks and pulls the guides in your default bundle. Commit the generated .claude/settings.json so the hooks are present in future clones.

The setup script runs when Claude builds the environment. Mossbear’s SessionStart hook updates the CLI and refreshes your guides when a later session reuses that environment.

5. Check the connection

Start a session and read the setup log. mossbear doctor should report a healthy dashboard connection. You can also ask Claude to run:

mossbear status
mossbear guides active

If the install works but the dashboard connection fails, check the allowed host before replacing the token. Package-manager access and dashboard access are separate settings.

Codex cloud

1. Create the environment

Open Codex environments, create an environment, and choose your repository.

2. Allow the dashboard and add the token

Turn on Allow Codex to access internet, leave Allow domains on Package managers, and add app.mossbear.io as an additional domain.

Add MOSSBEAR_TOKEN under Environment variables. The agent can read it, so use a token made just for this environment. Do not use Network secrets for it yet: Mossbear does not send its requests through the proxy that swaps in a secret’s value.

3. Add the install script

Paste this into Install script and leave Start skill empty:

npm install -g mossbear
mossbear init --no-prompt --platform codex --pull-guides || true
mossbear doctor || true

init pulls the guides in your default bundle and writes Mossbear’s skills to .agents/skills/, where Codex reads them.

Codex runs the install script when it prepares the environment, not for each task. To pick up guides you changed since, publish the environment again.

4. Check the result

Read the install log. If init could not reach the dashboard or pull your guides, it says so there. The || true lets the environment finish setting up either way.

Session grading

The steps above deliver your guides. Grading also needs Mossbear’s hooks to run during the task. Codex runs a project’s hooks only after someone trusts the project and reviews each hook in /hooks, and a cloud task cannot do either. Hooks in /etc/codex/config.toml skip that review, so to try grading, have the install script write the hooks from One setup for every local Codex session to that file. We have not yet confirmed that Codex cloud runs them.

What the token does

The token lets the CLI pull your Mossbear content and upload session activity. Mossbear reads it from MOSSBEAR_TOKEN; it does not need to save the value in ~/.mossbear/config.json.

Treat the token like a password:

• keep it in the cloud service’s secret or environment settings;
• never commit it;
• use one token per environment;
• disconnect it from Machines when that environment is retired or exposed.

You do not need an OpenAI, Anthropic, or OpenRouter API key in the container. The Mossbear dashboard performs grading after the CLI uploads the session.

Troubleshooting

Run this first:

mossbear doctor

• The token is rejected. Confirm that you copied the full token. Generate a replacement only if the old token is unavailable or revoked.
• The request is refused or reports a proxy. Add the dashboard host to the cloud environment’s network allowlist.
• Guides are empty. Check that the guides belong to the default bundle, then run mossbear refresh.
• Activity stays pending. The hooks are recording activity, but the agent phase cannot upload it. Check that the token is available during that phase and that POST requests to the dashboard are allowed.

For more diagnostic steps, see Troubleshooting.

Next step

On Claude Code on the web, once mossbear doctor is clean in the container, run a small task and find its session in your dashboard, as in Run a task and find its result. On Codex cloud the guides are delivered, but a session is not expected to appear until the hooks question under Session grading is settled. Every command and flag used above is in the CLI reference.