Skip to main content

Integration patterns

The system supports several integration styles. The right one depends on who the user is and where the work should happen.

Pattern 1: Product integration over HTTP​

Use the public HTTP API when you are building:

  • A web application.
  • A backend service.
  • An orchestration layer.
  • A workflow engine.

This is the default choice when you need a stable contract and do not need a local filesystem mount.

Pattern 2: Local filesystem access with Aether CLI​

Use Aether CLI when users need:

  • A local mount point.
  • Access from local editors or tools.
  • A shell-native development experience.
  • User-managed cache, logging, and metrics behavior.

This is the default choice for engineers, analysts, or operators working directly on a machine.

Pattern 3: Mixed workflow​

Many real deployments combine both approaches:

  • A product creates and manages sessions over HTTP.
  • A user opens a specific session locally with Aether CLI.
  • Review or persistence happens back through HTTP workflows.

This is often the best model because it separates control-plane logic from the local developer experience.

Pattern 4: Human-in-the-loop automation​

Use a mixed human/automation model when:

  • Tools generate or propose changes.
  • Humans must inspect or approve them.
  • Session metadata and approvals matter as much as file content.

Recommended surfaces:

  • HTTP for session creation, approvals, and workflow metadata.
  • Aether CLI for local inspection and editing.
  • Annotations, bus messages, and knowledge cache for coordination.

Pattern 5: Ephemeral task workers​

Use short-lived sessions for:

  • Batch processing.
  • Code or content transformation jobs.
  • Sandboxed analysis.
  • Per-task agent workspaces.

In this model, sessions are created, mutated, persisted if useful, and then retired quickly.

Choosing between API and CLI​

Choose the HTTP API when:

  • You are integrating software with software.
  • You need a programmatic service contract.
  • The user never needs a mount.

Choose Aether CLI when:

  • A human or local tool needs filesystem semantics.
  • Existing tools expect local paths.
  • You want local cache and debugging control.

Choose both when:

  • You need a product workflow plus a local editing surface.