> ## 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.

# Computers

> Namespace-owned durable computers, saved files, sessions, and history.

An IDYL Computer belongs to one Namespace and lives in one Subnet. Its name
is unique within the Namespace and Subnet together. Its stable ID and durable
state remain available independently of active execution.

| Surface | Scope | Purpose |
| - | - | - |
| Computer CRUD | Account + Namespace + Subnet | Create, inspect, update, list, or delete Computers. |
| Files and versions | Computer | Copy and inspect files, save versions, rewind, and fork. |
| Sessions | Computer | Run commands or open SSH sessions. |
| History | Computer | Read retained sessions and execution-setting changes. |

On the selected Subnet's public API, Computer routes are nested under:

```text theme={null}
/v1/accounts/{account}/namespaces/{namespace}/computers/{computer}
```

Direct Workload routes remain under the Namespace.

## Settings and execution

`spec.execution` records the requested image, CPU, memory, connectivity, and
environment variables. `executionSettings` reports the effective settings,
including whether a change is pending. The separate `execution` field reports
whether execution is dormant, waiting, or running.

Saved state belongs to the Computer. The idle timeout can release execution
without deleting that state. Use `idyl computer edit` to change settings and
`idyl computer history` to inspect recorded execution-setting changes.

## Lifecycle

Every Computer the API serves carries a `phase`:

| Phase | Meaning |
| - | - |
| `active` | The Computer is in service and accepts operations subject to authorization. |
| `terminating` | Deletion has been accepted and finalization is still pending. The Computer still resolves. |

### Deleting a Computer

Deletion is asynchronous. IDYL records the Computer as terminating, releases
what it owns, and finalizes the deletion. Once finalized, reads return 404 and
its name can be reused within the same Namespace and Subnet. Deleting a
Computer already terminating is accepted again.

Deletion releases the Computer's resources. Other Computers and direct
Workloads in the Namespace remain available. Deleting the Namespace releases
its Computers; see [Namespaces](https://docs.idyl.network/resources/namespaces.md#lifecycle).

### While terminating

| Operation | Result |
| - | - |
| Read the Computer or its retained state | Accepted |
| Delete the Computer or its retained state | Accepted |
| Create or edit state in the Computer | Refused with HTTP 409 and code `COMPUTER_TERMINATING` |

Automation should classify a refusal by its code. `terminatingAt` reports
when deletion was recorded.

### Observe and wait for deletion

```bash theme={null}
idyl computer get <computer> --namespace <namespace> --subnet <subnet>
idyl computer delete <computer> --namespace <namespace> --subnet <subnet> --yes --wait
```

`--wait` blocks until finalization. Use `--timeout` to bound the wait. After a
deletion is accepted, the equivalent wait command is:

```bash theme={null}
idyl wait computer <computer> --namespace <namespace> --subnet <subnet> --for deleted --timeout 10m
```

Both waits exit `0` when finalized and `124` when the timeout expires first.

## Related guides

* [Work in a Computer](https://docs.idyl.network/build/work-in-a-computer.md)
* [Computer concepts](https://docs.idyl.network/concepts/computers.md)
* [Namespaces](https://docs.idyl.network/resources/namespaces.md)
* [Computer command reference](https://docs.idyl.network/cli/reference/generated/computer)


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