Skip to content
ProductOS
Sign in Create a workspace

ProductOS Agent

Last updated:

A small program that runs on your machine. It executes the change definition of a pain in your own repository, with Claude Code or Codex, and you follow everything live in ProductOS.

  • Install the agent on your machine and sign in with your ProductOS account.
  • Link a git checkout of a repository connected in your workspace.
  • On a pain, Deliver and then Run: pick the machine and the tool.
  • The result is a branch and a commit in your repository, with a pull request when the GitHub CLI is installed.

1. What the ProductOS Agent is

The ProductOS Agent is a small executable you install on your own machine. It signs in as you, links your local git checkouts to the repositories your workspaces connect and detects the coding tools installed: Claude Code and Codex.

When you press Run in the Deliver dialog of a pain, the agent executes the change definition in the linked checkout: it edits, runs the tests, creates a branch, commits and opens a pull request.

The run shows in a drawer in ProductOS, where you follow each step and answer the tool's questions. The code never leaves your machine for ProductOS; only the run's events do.

2. Requirements

On the machine where the agent will run, you need:

  • git installed.
  • Claude Code (the claude command) or Codex CLI (the codex command), installed and signed in on this machine. You may have both.
  • A GitHub repository connected in your ProductOS workspace, and a checkout of it on this machine.
  • Optional: the GitHub CLI (the gh command), so the agent opens the pull request at the end.

3. Install

One static binary for Linux, macOS and Windows, amd64 and arm64. Pick the command for your platform:

macOS
brew install productos-technology/tap/productos-agent
Linux and macOS
curl -fsSL https://productos.technology/install.sh | sh
Windows
winget install ProductOS.Agent

Or download an archive from the releases on GitHub and put the productos-agent binary on your PATH. Checksums are in each version's checksums.txt.

4. First use

  1. Sign in with your account. The command opens the browser, you approve the agent and this machine is registered as one of your devices. The server is productos.technology; a self-hosted ProductOS is given as an argument.

    productos-agent login

  2. Link a checkout. Its origin remote must be a repository connected in your workspace; if it is not, the agent lists what ProductOS expected.

    productos-agent link ~/code/my-app

  3. Keep the agent connected: in the foreground, or as a service that starts with your session (systemd on Linux, launchd on macOS, Task Scheduler on Windows).

    productos-agent run
productos-agent service install

  4. In ProductOS, open a pain, press Deliver, pick this machine and the tool and press Run.

productos-agent status shows the server, the login, the tools, the device and the linked checkouts; productos-agent doctor checks every requirement.

5. How a run works

From the click on Run to the pull request, the agent always follows the same steps:

  1. The run arrives over the device's channel and the agent answers within 15 seconds.
  2. The checkout must be clean. The agent fetches the default branch from origin and creates from it a branch with the name ProductOS chose, such as productos/mob-p7-offline-drafts-are-lost.
  3. The tool runs unattended with the change definition as its prompt: it edits the code and runs the tests.
  4. Every message, tool call, changed file, test and log line becomes an event in the ProductOS drawer, in real time.
  5. If the tool asks a question, the run waits. You answer in the drawer and the session resumes where it stopped.
  6. When it is done, the work is committed as MOB-P7: Offline drafts are lost, with the trailer ProductOS: MOB-P7, the branch is pushed and, if gh is installed, a pull request is opened. The drawer shows the branch, the commit, the pull request link and a summary.

You can cancel at any time from the drawer: the tool's process is ended. A run that passes 2 hours is ended by the agent.

A run always ends in an outcome you can read: “Code changed” with the branch, the commit and the pull request; “No change needed” when the tool found the change already in the code (it says where; a person confirms it in the drawer); or a failure with its reason. Work the tool edited before a failure or a cancellation stays committed on the run's branch, so the next run starts from a clean checkout.

6. Updates

Before every run, the agent compares its version with the latest release ProductOS knows. When it is behind, it updates itself first (the archive is verified against the release's checksums), then runs the change on the new version. It never updates in the middle of a run, and a failed update never fails the run.

When the agent is idle, the same update happens as soon as it learns of a new version. You can also update by hand, or check what is available:

productos-agent update
productos-agent update --check

Installed with Homebrew or winget, the agent does not replace itself: it prints the package manager's command instead. A device below the minimum version ProductOS supports cannot start runs until it is updated; the Deliver dialog says so.

To turn the automatic update off, set "auto_update": false in the agent's config.json, or export PRODUCTOS_AGENT_NO_UPDATE=1.

7. Security

  • The agent only runs in checkouts you linked, and a checkout only links when its remote matches a repository connected in your workspace. The server checks this on every run.
  • The device belongs to your account. Only you can start runs on it; to anyone else, it does not exist.
  • Tokens live in the operating system's keychain. Access tokens last one hour and are refreshed with rotation.
  • The agent never receives cookies, CSRF tokens or anyone's secrets. The change definition names no customer.
  • To revoke a device, use Account and then Devices in ProductOS, or productos-agent logout on the machine. This cancels the runs in progress and drops the links.

8. Common problems

Device offline

The agent is not running or has not talked to the server for more than 90 seconds. Check its state and connect again, in the foreground or through the service:

productos-agent status
productos-agent run
productos-agent service start
Repository not linked

The pain belongs to a product whose repository has no linked checkout on this machine. Enter the checkout and link it:

cd ~/code/my-app
productos-agent link
Tool not found

The chosen tool is not on this machine's PATH or is not signed in. Install Claude Code or Codex, sign in to the tool and check:

productos-agent doctor

--verbose on any command also writes the log to the terminal. The structured log is agent.log, in the agent's state directory; tokens and change definitions are never written.

9. Source and licence

The agent's source is open, at github.com/productos-technology/productos-agent, under the MIT licence.

The contract between the agent and the server is docs/reference/agent-protocol.md, in the ProductOS repository.