Sandboxed Environments

Share traces from GitHub Actions, Docker, CI/CD pipelines, and other headless environments.

Traces works in any environment where you can run the CLI or make HTTP requests. In sandboxed environments, use an API key instead of interactive login.

Authentication

# Set the API key as an environment variable
export TRACES_API_KEY=trk_your_api_key_here

# Or pass it directly
traces share --cwd . --key trk_your_api_key_here

Generate API keys at traces.com/@your-namespace/settings/api-keys. Keys start with trk_ and are scoped to a namespace.

GitHub Actions

name: Share Trace
on: [push]
jobs:
  share:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Traces CLI
        run: |
          curl -fsSL https://www.traces.com/install | bash
          echo "$HOME/.traces/bin" >> $GITHUB_PATH

      - name: Run agent task
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: claude --print "Review this code for bugs"

      - name: Share trace
        env:
          TRACES_API_KEY: ${{ secrets.TRACES_API_KEY }}
        run: |
          RESULT=$(traces share --cwd . --agent auto --json)
          echo "$RESULT"
          URL=$(echo "$RESULT" | jq -r '.data.sharedUrl')
          echo "### Trace shared" >> $GITHUB_STEP_SUMMARY
          echo "[$URL]($URL)" >> $GITHUB_STEP_SUMMARY

Comment trace URL on a pull request

name: PR Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review-and-share:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4

      - name: Install Traces CLI
        run: |
          curl -fsSL https://www.traces.com/install | bash
          echo "$HOME/.traces/bin" >> $GITHUB_PATH

      - name: Run agent review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: claude --print "Review this PR for bugs and security issues"

      - name: Share trace
        id: share
        env:
          TRACES_API_KEY: ${{ secrets.TRACES_API_KEY }}
        run: |
          RESULT=$(traces share --cwd . --agent auto --json)
          URL=$(echo "$RESULT" | jq -r '.data.sharedUrl')
          echo "url=$URL" >> $GITHUB_OUTPUT

      - name: Comment on PR
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `Agent review trace: ${{ steps.share.outputs.url }}`
            })

Docker

FROM node:22-slim

# Install Traces CLI
RUN curl -fsSL https://www.traces.com/install | bash \
    && ln -s /root/.traces/bin/traces /usr/local/bin/traces

WORKDIR /app
COPY . .

CMD ["sh", "-c", "claude --print \"$PROMPT\" && traces share --cwd . --agent auto --json"]

Run with your API keys:

docker run \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -e TRACES_API_KEY="$TRACES_API_KEY" \
  -e PROMPT="Analyze this codebase" \
  my-agent-image

Headless / SSH (no browser)

export TRACES_API_KEY=trk_your_key_here
traces share --cwd . --agent auto --json
# No traces login needed -- the API key handles auth

GitLab CI

share-trace:
  image: node:22-slim
  script:
    - curl -fsSL https://www.traces.com/install | bash
    - export PATH="$HOME/.traces/bin:$PATH"
    - claude --print "Review this MR"
    - traces share --cwd . --agent auto --json
  variables:
    TRACES_API_KEY: $TRACES_API_KEY
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY

Without the CLI (curl only)

In environments where you can't install the CLI, use the REST API directly:

#!/bin/bash
set -euo pipefail

TRACES_API_KEY="${TRACES_API_KEY:?Set TRACES_API_KEY}"
BASE_URL="https://actions.traces.com"
TRACE_ID="ci-$(date +%s)-${GITHUB_RUN_ID:-local}"

# Create the trace
curl -sf -X PUT "$BASE_URL/v1/traces/$TRACE_ID" \
  -H "Authorization: Bearer $TRACES_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"title\": \"CI Run $(date -u +%Y-%m-%dT%H:%M:%SZ)\",
    \"agent\": \"ci-bot\",
    \"visibility\": \"private\"
  }"

# Upload messages in a batch
curl -sf -X POST "$BASE_URL/v1/traces/$TRACE_ID/messages/batch" \
  -H "Authorization: Bearer $TRACES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "externalId": "msg_001",
        "role": "user",
        "parts": [{"type": "text", "text": "Analyze codebase"}]
      },
      {
        "externalId": "msg_002",
        "role": "assistant",
        "parts": [{"type": "text", "text": "Found 3 potential issues..."}]
      }
    ]
  }'

Environment variables

Variable	Required	Description
`TRACES_API_KEY`	Yes	API key for authentication (`trk_*`)
`TRACES_CURRENT_TRACE_ID`	No	Override session resolution with an exact trace ID
`TRACES_CURRENT_SOURCE_PATH`	No	Override session resolution with an exact source path
`TRACES_CURRENT_AGENT`	No	Override agent detection

Tips

Always use --json in CI for machine-readable output.
Use --agent auto when you don't know which agent produced the session.
Set visibility to private for CI traces with proprietary code.
Store TRACES_API_KEY as a secret in your CI provider -- never commit it.

Sandboxed Environments

On this page