Workspaces - IDYL Docs

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:

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

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.

idyl workspace get <workspace> --namespace <namespace>

Output similar to:

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.

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.

​Lifecycle

​Deleting a workspace

​While terminating

​Termination detail

​Observe a deletion

​Wait for finalization

​Related guides