Skip to main content
Use this page to connect developers’ machines and repositories to a shared Sediment deployment, and to verify that each agent’s work arrives. Start with a deployment from Deploy Sediment on EC2 or Deploy Sediment on your own host that passes its HTTPS health check. Before enrollment, agree with participants which repositories and agents Sediment captures. Privacy boundaries lists what each capture path records.

​
Create a capture token for each developer

Each developer machine gets its own named capture token. A capture token can send data but can’t read it.
  1. Stop Sediment.
  2. For each machine, generate a token:
  3. In a private editor, add one SEDIMENT_INGEST_TOKENS line to ~/.sediment/server/server.env. Its value is a JSON object that maps each machine’s name to its token:
    The names operator, legacy, and retrieval are reserved. Keep the file mode at 0600.
  4. Start Sediment.
  5. Send each developer only their own token through a private channel. Keep SEDIMENT_OPERATOR_TOKEN and the rest of server.env to yourself.
To add a developer later, repeat these steps, and add their entry to the existing SEDIMENT_INGEST_TOKENS object.

​
Connect your repositories

  1. Create the GitHub webhooks for Pushes, CI, pull requests, and repository changes.
  2. For private repositories, give the server read-only mirror credentials.

​
Install Sediment on each machine

Each developer runs these steps on a macOS or Linux machine with Git and curl on PATH.
  1. Install the version that your deployment runs. /health reports it:
    If the installer prints a PATH instruction, run it. Then check that sediment --version prints the same version.
  2. Install and sign in to each agent through its normal setup. Start and close it once so that its configuration directory exists.
  3. Enroll the machine. Replace the deployment URL, developer identifier, and repository path:
    login --capture prompts for the developer’s capture token. install configures every agent that it detects. If the developer doesn’t use Codex, omit --codex-profile sediment. Resolve every FAIL from doctor.
Optional capture needs separate consent and setup:

​
Verify capture

A /health response and organization-wide Fact counts don’t prove capture. Check one real Session for each agent that the team uses.
  1. On an enrolled machine, also sign in with the operator token, and create a scratch branch:
  2. Load . "$HOME/.sediment/env.sh", and start the agent from that shell:
  3. Ask the agent to create a small file, and end the Session. Use Cursor Agent rather than Tab, pi’s write tool, and a single-file patch in Codex.
  4. Commit only that file, and read the commit’s Session note:
  5. Copy the session_id from the note, and check that Session on the server. Set --agent to codex, cursor, or pi:
    Each check reports ok. If you enabled transcript or gateway capture, add --transcripts or --inference-calls. Cursor supports neither flag. For Claude Code, doctor --agent isn’t available. Run sediment facts before and after the Session, and check that developer_decisions grew.
Repeat steps 2–5 for each agent, and commit each agent’s file before you test the next. Let telemetry flush before you investigate a failure. To fix one, see the agent’s page in Agent integrations.

​
Verify forge delivery

Push the scratch branch, and check that the server linked the commit to its Session:
The remote has refs/notes/sediment, and sediment commit lists the Session. After the CI workflow finishes, the commit also shows its CI outcome. Merge retention needs a real pull-request merge, so verify one before you read that report.

​
Know what each agent captures

Agents supply different evidence, so compare them with care:
  • Cursor supplies neither Inference calls nor Edit observations.
  • Cursor and pi accepts, and automatic Codex approvals, are implicit. Reports don’t count them as human-explicit accepts.
  • Session-end retention needs Edit observations. Merge retention also needs pull-request webhooks.
  • Missing evidence isn’t a negative outcome.
Compare integrations lists each agent’s signals. Next, measure agent work.

​
Remove a developer

  1. If the machine runs a sender replay worker, drain and stop it with Preserve prepared payloads through outages.
  2. On the machine, remove capture from each repository:
    To remove the machine-wide agent hooks too, follow Uninstall capture.
  3. On the server, revoke the token.
Stored Facts and existing commit notes remain.