Skip to main content

Build an agent runner

This guide is for teams building agents, orchestrators, or workflow runners on top of the public AetherFS surface.

What you are building​

A basic agent runner usually needs to:

  • create or receive a session
  • discover the filesystem tree
  • mutate files or paths
  • store workflow state
  • request approval for important actions
  • commit or promote when done

The minimum viable agent runner​

If you want the smallest useful runner, build these phases:

1. Session acquisition​

Use:

  • POST /v1/sessions
  • GET /v1/sessions/{sessionId}

The session is the unit of work.

2. Tree discovery​

Use:

  • GET /v1/sessions/{sessionId}/manifest

Do not start by guessing raw file routes.

3. Mutation​

Use the simplest valid public route for the job:

  • dirs
  • rename
  • delete
  • batch
  • patchSegments

Start simple. Use sparse or advanced routes only when the workflow actually needs them.

4. Workflow state​

Use:

  • cache for keyed structured state
  • bus for live progress
  • annotations for durable review notes

5. Recoverability​

Use:

  • checkpoints before risky changes

6. Approval​

Use:

  • POST /v1/sessions/{sessionId}/request-approval

The runner should pause cleanly when approval is required.

7. Persistence​

Use:

  • commit
  • merge if needed
  • promote session to source if the outcome should become a future baseline

Build in this order:

  1. create session
  2. get manifest
  3. simple path mutation
  4. cache and bus
  5. checkpoints
  6. approval request
  7. commit

That order gives you a useful runner quickly and keeps the control flow understandable.

Choosing the right mutation surface​

Use:

  • simple path routes for simple changes
  • batch when one action really contains several writes or deletes
  • patchSegments when partial updates or sparse writes matter

Avoid over-using the most advanced route just because it exists.

Choosing the right metadata surface​

Use:

  • cache for structured state
  • bus for ephemeral coordination
  • annotations for review-visible notes
  • events for historical investigation

Approval design guidance​

A strong agent runner:

  • requests approval with a machine-readable reason
  • includes enough human detail to make the decision easy
  • treats denial as a normal workflow branch, not as a crash

Persistence design guidance​

Do not use commit as a “save progress” action.

Use:

  • checkpoints for progress protection
  • commits for durable results
  • promotions for baseline updates

What to leave out at first​

You probably do not need at first:

  • xattrs
  • POSIX locks
  • collaboration file locks
  • source lifecycle UI

Build the core session and mutation flow first.

What success looks like​

A successful agent runner:

  • creates clean session-scoped work
  • avoids stale mutation assumptions
  • survives retries and review pauses
  • produces a durable result only when the workflow allows it