Skip to main content
Version: next

Context workflows

Preview. This is a planning list, not a description of shipped behavior: the Status column says which workflows work today. Known limits of what has shipped: Runs.

Moca runs agent tasks remotely. Many of those tasks need context: files, repositories, memory or data that the task works from. This page lists the ways we expect people to move context into and out of moca, and what each one needs. It is a living list; propose changes in a PR.

A workload is an environment for delegated tasks: where they run and the context they work from (Context Service and workloads). Today a workload belongs to the user who created it. Context is stored by Context Service.

Workflows​

Arrows show where the context starts and where the work happens. laptop is any local agent harness, moca is where the delegated tasks run, and Context Service is where context is stored.

Delegate work from a laptop​

#WorkflowFlowWhen to use itSandboxStorageStatus
1Delegate one local tasklaptop → mocaOffload one bounded taskSharedContext PVC, copied in read-onlyServer done; client next
2Fan out local taskslaptop → moca ⇉ N tasksRun many independent tasks in parallelSharedContext PVC, copied in read-onlyServer done; client next
3Delegate tasks as separate usersA → moca ← BSeveral users delegate without seeing each otherPer-workloadEach user's Context PVC, mountedPlanned (#476)

Keep context in moca​

#WorkflowFlowWhen to use itSandboxStorageStatus
4Share an always-on workspacegit → moca ← usersMany users' agents work on the same loaded reposPer-workloadDurable PVC, mounted read-writePlanned (#476); sharing to do
5Reuse a remote datasetstored Context → new workloadsAvoid uploading the same data againEitherExisting Context PVCPlanned (#358)
6Share trusted reference dataone read-only Context ⇉ agentsGive many tasks the same source material safelyPer-workloadExisting Context PVC, read-onlyPlanned (#358); sharing to do
7Share a collaboration workspaceagents ⇄ moca (read-write)Combine intermediate results across tasksPer-workloadDurable PVC, mounted read-writePlanned (#476); sharing to do

Move context between places​

#WorkflowFlowWhen to use itSandboxStorageStatus
8Return remote artifactsmoca → laptopContinue remote work locallyEitherSandbox output → local filesNo design yet
9Hand work to another agentagent A → Context Service → agent BMove work across harnesses—Context PVCCapture and restore exist; cross-harness translation to do
10Replicate local contextlaptop → Context ServiceKeep local work ready to delegate (feeds workflow 5)—Local files → Context PVCExists (contextctl backup)

Sandbox and storage types​

Sandboxes:

  • Shared: the operator's shared, statically provisioned sandboxes. Tasks from many workloads run on them. They are not a security boundary between users: tasks from different users can run on the same sandbox, as the same Linux user, one after another, and read-only is enforced only by file permissions.
  • Per-workload: sandboxes moca creates for one workload and deletes with it.
  • Either: the workflow works with both.

Storage:

  • Context PVC: the PVC Context Service keeps for a workload's Context.
    • Copied in read-only: shared sandboxes can't mount a new PVC, so moca copies the frozen context into the sandbox for each task and removes it afterwards.
    • Mounted: a per-workload sandbox mounts the PVC directly. In per-workload sandboxes (#476), delegated tasks mount it rather than copying from it.
  • Durable PVC: a PVC that lives as long as the workload, mounted read-write, for state the tasks build up, such as cloned repositories.
  • Existing Context PVC: a Context that already exists, used instead of a new upload, and authorized by Context Service's per-user permissions rather than a PVC name.

Status​

  • Server done; client next: the routes exist — #482 (/workloads phase 1) and #494 (run tasks on a workload's context). The command-line client and delegate skill are designed in #495 (one CLI for delegating subagent tasks). Today's limits: workload runs are synchronous only, they need a logged-in user, and the routes are off unless the operator enables them (see Runs).
  • Planned (#476): #476 (phase 2: per-workload sandboxes and storage).
  • Planned (#358): #358 (per-user PVC authorization).
  • Sharing to do: more than one user using the same workload or Context. Not designed yet.
  • Capture and restore exist: Context Service already captures and restores native agent-harness state for Claude Code, Codex, OpenCode and Pi (harness attachments, portability). What's missing is translating one harness's state into another's.

Workflow notes​

3. Delegate tasks as separate users. User A and user B each delegate tasks. Each user's tasks run in that user's own sandboxes with that user's context, and neither can see the other's.

4. Share an always-on workspace. Someone creates a workload with a durable PVC once and keeps it running. Instead of uploading files, a moca task populates the PVC from inside the sandbox, for example by cloning repositories, and later tasks refresh it with git pull. One or many users' agents then work in the same loaded workspace. The motivating case is BugStone, a pipeline project whose repositories stay loaded in its sandboxes.

5. Reuse a remote dataset. Upload the context once and keep it. Later workloads, in other batches or days later, point at the same Context instead of uploading again. Unlike workflow 2, the Context outlives the workload that first used it.

9. Hand work to another agent. Context Service already captures an agent harness's native state (for example a Claude Code session) and restores it into the same kind of harness. Continuing the work in a different harness (for example Codex or Pi) needs translation between their formats. Moca is not involved.

10. Replicate local context. contextctl backs a local context up to Context Service continuously, so it is already remote when you delegate; the delegation then reuses it as in workflow 5.