CommRails - Allternit Docs

Overview

CommRails (the Allternit Agent System Rails) is the unified execution and coordination substrate for local and platform-hosted agents. It combines an append-only ledger, policy gates, directed-acyclic-graph work identities (WIHs), peer-to-peer messaging, and durable leases into one workspace-scoped service. CommRails powers:

Cross-session agent peer discovery and messaging
Event-sourced work planning, DAG execution, and handoffs
Policy enforcement and steering checkpoints
Receipts, vault archival, and context-pack checkpoints
Ticket tracking with graph analytics and external-tracker sync

The HTTP surface is mounted in allternit-api at /api/rails and /rails, and is also available as the standalone allternit-rails-service on port 3011.

Base URL

https://api.allternit.com/api/rails

Local development (allternit-rails-service):

http://127.0.0.1:3011

All routes below are relative to the base URL. Requests must include an Authorization: Bearer <token> header unless the instance is configured for open local use.

Endpoints

Peers

Method	Path	Description
`GET`	`/peers`	List registered local peers
`POST`	`/peers`	Register a new peer
`DELETE`	`/peers/:id_or_name`	Unregister a peer
`POST`	`/peers/:id_or_name/heartbeat`	Refresh peer heartbeat
`POST`	`/peers/:id_or_name/send`	Send a plain-text message to a peer
`GET`	`/peers/:id_or_name/inbox`	Poll a peer’s HTTP inbox

Steering

Method	Path	Description
`POST`	`/steer/checkpoint`	Hash `.steering/checkpoint.md` and emit a `SteeringCheckpoint` event
`POST`	`/steer/consult`	Build steering context and consult the configured backend
`POST`	`/steer/commit-gate`	Commit/push approval consult

Ledger

Method	Path	Description
`GET`	`/ledger/events`	Query ledger events
`POST`	`/ledger/tail`	Tail the most recent ledger events

Receipts

Method	Path	Description
`POST`	`/receipts`	Query receipt records
`POST`	`/receipts/write`	Write a new receipt

Mail

Method	Path	Description
`POST`	`/mail/send`	Send a mail message (legacy or typed envelope)
`GET`	`/mail/threads`	List mail threads
`GET`	`/mail/thread/:thread_id`	Read messages in a thread
`POST`	`/mail/share`	Share an asset into a thread
`POST`	`/mail/decide`	Record a review decision
`GET`	`/mail/agents`	List registered mail agents
`POST`	`/mail/agents/register`	Register a mail agent identity
`GET`	`/mail/inbox/:agent_id`	Read an agent’s inbox
`GET`	`/mail/outbox/:agent_id`	Read an agent’s outbox
`GET`	`/mail/search`	Full-text search mail messages
`GET`	`/mail/overdue`	List overdue/unacknowledged messages

WIHs

Method	Path	Description
`GET`	`/wihs`	List Work Identity Handles
`POST`	`/wihs`	List WIHs (POST variant)
`POST`	`/wihs/pickup`	Pick up a WIH for an agent
`GET`	`/wihs/:wih_id/context`	Get the WIH context pack
`POST`	`/wihs/:wih_id/sign`	Sign open a WIH
`POST`	`/wihs/:wih_id/close`	Close a WIH with status and evidence

DAGs

Method	Path	Description
`GET`	`/workspace/:workspace_id/dags`	List DAGs
`POST`	`/workspace/:workspace_id/dags`	Create a DAG
`GET`	`/workspace/:workspace_id/dags/:dag_id`	Get DAG details
`POST`	`/workspace/:workspace_id/dags/:dag_id/start`	Start DAG execution

Leases

Method	Path	Description
`POST`	`/leases`	Request a resource lease
`GET`	`/leases/:lease_id`	Get lease status

Context packs

Method	Path	Description
`POST`	`/workspace/:workspace_id/packs`	Create a context-pack checkpoint
`GET`	`/workspace/:workspace_id/packs/:pack_id`	Retrieve a context pack

Gate / policy

Method	Path	Description
`POST`	`/gate/evaluate`	Evaluate a policy decision

Vault

Method	Path	Description
`GET`	`/vault/status`	List completed vault archive jobs
`POST`	`/vault/archive`	Archive a WIH to the vault

Tickets

Method	Path	Description
`POST`	`/tickets`	Create a ticket
`GET`	`/tickets`	List tickets
`GET`	`/tickets/ready`	List ready tickets
`GET`	`/tickets/blocked`	List blocked tickets
`GET`	`/tickets/:id`	Get a ticket
`PATCH`	`/tickets/:id`	Update a ticket
`POST`	`/tickets/:id/close`	Close a ticket
`POST`	`/tickets/:id/reopen`	Reopen a ticket
`POST`	`/tickets/:id/dependencies`	Add a dependency
`DELETE`	`/tickets/:id/dependencies`	Remove a dependency

Graph analytics

Method	Path	Description
`GET`	`/graph/insights`	Dependency-graph insights
`GET`	`/graph/triage`	Ranked ready tickets
`GET`	`/graph/impact/:ticket_id`	Impact analysis for a ticket

Request / response examples

Register a peer

curl -X POST https://api.allternit.com/api/rails/peers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "gizzi-session-42",
    "vendor": "gizzi",
    "cwd": "/Users/joe/project"
  }'

{
  "peer_id": "peer_abc123def456",
  "name": "gizzi-session-42",
  "inbox_socket": "/Users/joe/project/.allternit/peers/inbox/peer_abc123def456.sock"
}

Send a message to a peer

curl -X POST https://api.allternit.com/api/rails/peers/gizzi-session-42/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "List peers and report back",
    "from": "orchestrator"
  }'

{
  "delivered": true,
  "error": null
}

Poll a peer inbox

curl "https://api.allternit.com/api/rails/peers/gizzi-session-42/inbox?limit=10" \
  -H "Authorization: Bearer $TOKEN"

{
  "messages": [
    {
      "id": 1,
      "correlation_id": "evt_xxx",
      "to": "peer:gizzi-session-42",
      "from": "orchestrator",
      "kind": "peer_envelope",
      "payload": {
        "body": "List peers and report back",
        "from": "orchestrator"
      },
      "transport": "http",
      "status": "pending"
    }
  ]
}

Query the ledger

curl "https://api.allternit.com/api/rails/ledger/events?dag_id=dag_123&limit=20" \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "event_id": "evt_abc123",
    "ts": "2026-08-13T19:50:00Z",
    "actor_type": "agent",
    "actor_id": "agent-1",
    "event_type": "DagNodeCreated",
    "payload": {
      "dag_id": "dag_123",
      "node_id": "dag_123-root",
      "title": "Fix login bug"
    },
    "scope": {
      "dag_id": "dag_123",
      "wih_id": null,
      "run_id": null
    }
  }
]

Create a ticket

curl -X POST https://api.allternit.com/api/rails/tickets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add OAuth login",
    "description": "Support OAuth-based sign-in",
    "kind": "feature",
    "priority": "P1",
    "labels": ["auth", "backend"]
  }'

{
  "ticket": {
    "id": "T-abc123...",
    "title": "Add OAuth login",
    "status": "open",
    "kind": "feature",
    "priority": "P1",
    "labels": ["auth", "backend"],
    "created_at": "2026-08-13T19:50:00Z",
    "updated_at": "2026-08-13T19:50:00Z"
  }
}

Request a lease

curl -X POST https://api.allternit.com/api/rails/leases \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wih_id": "wih_123",
    "agent_id": "agent-1",
    "paths": ["src/auth/*", "docs/auth.md"],
    "ttl_seconds": 600
  }'

{
  "lease_id": "lease_abc123",
  "status": "requested"
}

Create a DAG

curl -X POST https://api.allternit.com/api/rails/workspace/ws_1/dags \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Refactor checkout",
    "description": "Split monolithic checkout module"
  }'

{
  "dag_id": "dag_abc123",
  "status": "created"
}

Pick up a WIH

curl -X POST https://api.allternit.com/api/rails/wihs/pickup \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dag_id": "dag_abc123",
    "node_id": "dag_abc123-root",
    "agent_id": "agent-1",
    "role": "builder",
    "fresh": false
  }'

{
  "wih_id": "dag_abc123:dag_abc123-root",
  "context_pack_path": null
}

Archive a WIH to the vault

curl -X POST https://api.allternit.com/api/rails/vault/archive \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "wih_id": "wih_123" }'

{
  "archived": true,
  "path": "/workspace/.allternit/vault/wih_123/..."
}

Error codes

Status	Meaning
`200 OK`	Request succeeded
`201 Created`	Resource created successfully
`400 Bad Request`	Invalid request body or parameters
`401 Unauthorized`	Missing or invalid bearer token
`404 Not Found`	Peer, ticket, WIH, or lease not found
`500 Internal Server Error`	Ledger, store, or unexpected service error

Error responses follow this shape:

{
  "error": "peer not found"
}

Concepts

Peer — a registered local agent session. Peers discover each other via the workspace registry and can exchange plain-text messages over UDS or HTTP polling.
WIH — Work Identity Handle, the runtime envelope for a single DAG node.
DAG — directed dependency graph of work nodes.
Lease — scoped, time-bounded permission to read/write paths or use tools.
Ledger — append-only event log that is the source of truth for all Rails state.
Gate — policy enforcer that checks leases, receipts, and injected policy bundles before mutations.
Vault — archival store for completed WIH artifacts.
Context pack — sealed checkpoint of inputs and policy bundles for reproducible execution.

​Overview

​Base URL

​Endpoints

​Peers

​Steering

​Ledger

​Receipts

​Mail

​WIHs

​DAGs

​Leases

​Context packs

​Gate / policy

​Vault

​Tickets

​Graph analytics

​Request / response examples

​Register a peer

​Send a message to a peer

​Poll a peer inbox

​Query the ledger

​Create a ticket

​Request a lease

​Create a DAG

​Pick up a WIH

​Archive a WIH to the vault

​Error codes

​Concepts

​Related links