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

# Workspaces

> Namespace-owned durable context, files, and Run history.

A Workspace is owned by one Namespace. Its name is unique within that
Namespace and its durable state remains available independently of running
Workloads.

| Surface           | Scope                           | Purpose                                                     |
| ----------------- | ------------------------------- | ----------------------------------------------------------- |
| Workspace CRUD    | Account + Namespace             | Create, inspect, update, list, or delete logical computers. |
| Files             | Account + Namespace + Workspace | Store and retrieve small durable files by relative path.    |
| Runs              | Account + Namespace + Workspace | Snapshot files and retain execution attempt history.        |
| Composed Workload | Account + Namespace             | Perform each Run attempt on the normal Workload substrate.  |

Workspace-local routes are nested under:

```text theme={null}
/v1/accounts/{account}/namespaces/{namespace}/workspaces/{workspace}
```

Direct Workload routes remain under the Namespace and contain no Workspace
segment.

## Lifecycle

A Workspace is in one of two phases. Every Workspace the API serves carries a
`phase`.

| Phase         | Meaning                                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------------------------------- |
| `active`      | The Workspace is in service. It resolves, and every Workspace-local operation is accepted subject to authorization. |
| `terminating` | A deletion has been accepted and the platform has yet to finalize it. The Workspace still resolves.                 |

### Deleting a workspace

Deleting a Workspace is asynchronous. The API accepts the request with HTTP
202 and records the Workspace as `terminating`. The platform then stops the
Workloads of the Workspace's Runs and removes its files, revisions, Runs, and
attempts. Once nothing remains, the platform finalizes the release. A
finalized Workspace resolves 404, and its name is free to reuse within the
Namespace. Deleting a Workspace that is already terminating is accepted again
with the same result.

A Workspace deletion releases only what the Workspace owns. Every other
resource in the Namespace, including direct Workloads and other Workspaces,
is left in place. Deleting the Namespace releases every Workspace within it;
see [Namespaces](/resources/namespaces#lifecycle).

### While terminating

| Operation                              | Result                                                 |
| -------------------------------------- | ------------------------------------------------------ |
| Read the Workspace or anything in it   | Accepted                                               |
| Delete the Workspace or anything in it | Accepted                                               |
| Create anything in the Workspace       | Refused with HTTP 409 and code `WORKSPACE_TERMINATING` |
| Edit the Workspace or anything in it   | Refused with HTTP 409 and code `WORKSPACE_TERMINATING` |

The refusal's details name the Namespace and the Workspace. Automation should
classify the refusal by its code.

### Termination detail

While a Workspace is terminating, the API reports `terminatingAt`, the instant
the deletion was recorded, and `termination`, which describes what still holds
finalization back.

| Field           | Meaning                                                                       |
| --------------- | ----------------------------------------------------------------------------- |
| `runsRemaining` | Runs that have yet to reach a terminal status: succeeded, failed, or stopped. |

The platform finalizes once no Runs remain.

### Observe a deletion

`idyl workspace get` lists the Workspaces of a Namespace with a `PHASE`
column. With a name, it shows the phase and, for a terminating Workspace, the
Runs still to finish.

```bash theme={null}
idyl workspace get <workspace> --namespace <namespace>
```

Output similar to:

```text theme={null}
Name         payments
Namespace    production
ID           019ad9ba-7334-7eca-9958-9f00c6c9f802
Account ID   550000000001
Description  Payments platform
Phase        Terminating
Terminating  3m ago
Runs         2 remaining
Created      Jun 1
Updated      Jun 1
```

### Wait for finalization

Pass `--wait` to `idyl workspace delete` to block until the Workspace is
finalized, and `--timeout` to bound the wait. After a deletion has been
accepted, `idyl wait workspace <workspace> --for deleted` blocks the same way.

```bash theme={null}
idyl workspace delete <workspace> --namespace <namespace> --yes --wait
idyl wait workspace <workspace> --namespace <namespace> --for deleted --timeout 10m
```

Both exit `0` when the Workspace is finalized and `124` when the timeout
passes first. While the Workspace is terminating, the wait reports the Runs
still to finish.

## Related guides

* [Work in a Workspace](/build/work-in-a-workspace)
* [Workspace concepts](/concepts/workspaces)
* [Namespaces](/resources/namespaces)