> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Jobs

> Where a workspace keeps background jobs and processes, and which instance of it runs them.

The execution store keeps:

* Each session's background jobs, the ones `cmd &` starts, and each job's
  output.
* The processes the workspace runs, which `ps` lists.
* Which instance of the workspace runs them, and when it was last seen.

| `type` | Keeps them | Keys |
| - | - | - |
| `ram` | In the process's memory. Jobs end with the process. | |
| `redis` | On Redis, under `key_prefix` and the workspace id. A job's output stays a day after its last write. | `url`, `key_prefix`, default `mirage:` |

The group key is `store.execution`. A job's output is a stream other
processes follow, so `disk` is refused here, and a `disk` store keeps its
jobs in memory.

In code, `SqlWorkspaceStateStore` keeps them in a SQL database, SQLite or
Postgres, in two tables it makes on first use, so every process on the
database lists the same jobs, lines and processes, and a restart on it keeps
them. A reader following a job on another process there sees new output
within a quarter of a second.

## On Redis

> [tab] YAML
>
> ```yaml theme={null}
> workspace_id: agent
> store:
>   type: disk
>   root: /var/lib/mirage
>   execution:
>     type: redis
>     url: redis://redis.internal:6379/0
> ```

> [tab] Python
>
> ```python theme={null}
> from mirage import Workspace
> from mirage.workspace.store import DiskWorkspaceStateStore, RedisWorkspaceStateStore
>
> store = DiskWorkspaceStateStore(
>     root="/var/lib/mirage",
>     execution=RedisWorkspaceStateStore(url="redis://redis.internal:6379/0"),
> )
> ws = Workspace(mounts, workspace_id="agent", store=store, owns_store=True)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { DiskWorkspaceStateStore, RedisWorkspaceStateStore, Workspace } from '@struktoai/mirage-node'
>
> const store = new DiskWorkspaceStateStore({
>   root: '/var/lib/mirage',
>   execution: new RedisWorkspaceStateStore({ url: 'redis://redis.internal:6379/0' }),
> })
> const ws = new Workspace(mounts, { workspaceId: 'agent', store, ownsStore: true })
> ```

Here the rest of the state stays on the machine's disk, and every process on
the machine that builds the workspace sees the same jobs.

## Several instances of one workspace

Every process that builds the workspace under the same id on one Redis is an
instance of it, on one machine or several, behind a load balancer or as
replicas of one agent.

> [tab] YAML
>
> ```yaml workspace.yaml theme={null}
> workspace_id: agent
> store:
>   type: redis
>   url: redis://redis.internal:6379/0
> mounts:
>   /data:
>     vfs: s3
>     config:
>       bucket: agent-data
> ```

> [tab] Python
>
> ```python theme={null}
> from mirage import MountMode, Workspace
> from mirage.vfs.s3 import S3VFS, S3Config
> from mirage.workspace.store import RedisWorkspaceStateStore
>
> ws = Workspace(
>     {"/data": S3VFS(S3Config(bucket="agent-data"))},
>     mode=MountMode.WRITE,
>     workspace_id="agent",
>     store=RedisWorkspaceStateStore(url="redis://redis.internal:6379/0"),
>     owns_store=True,
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { MountMode, RedisWorkspaceStateStore, S3VFS, Workspace } from '@struktoai/mirage-node'
>
> const ws = new Workspace(
>   { '/data': new S3VFS({ bucket: 'agent-data' }) },
>   {
>     mode: MountMode.WRITE,
>     workspaceId: 'agent',
>     store: new RedisWorkspaceStateStore({ url: 'redis://redis.internal:6379/0' }),
>     ownsStore: true,
>   },
> )
> ```

> [tab] Servers
>
> ```bash theme={null}
> for server in http://mirage-a:8765 http://mirage-b:8765; do
>   curl "$server/v1/workspaces" \
>     -H "Authorization: Bearer $MIRAGE_AUTH_TOKEN" \
>     -H 'Content-Type: application/json' \
>     --data-binary @workspace.json
> done
> ```

On the servers, `workspace.json` holds `{"id": "agent", "config": {...}}`
with the same config on each. Then:

* One instance runs the workspace's lines at a time: the first to run one.
  Any other is refused with an error naming that instance, which a server
  answers with `409`, until it stops, deletes or closes the workspace.
* If it goes away without doing so, the workspace is free 30 seconds after
  it was last seen. The next instance to run a line reports the jobs it left
  as ended with status 129 and stops the programs they left running.
* A server keeps its id under its state root, so a restarted server runs its
  workspaces again at once.
* Sessions and symlinks are shared, since the whole store is on Redis.

A session sees only its own processes; a profile with
[`processes: workspace`](https://docs.mirage.strukto.ai/home/configuration/session) widens that to every session's.
[Shell](https://docs.mirage.strukto.ai/home/core/shell.md#jobs-across-instances) describes the details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.