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

# Work in a Workspace

> Create a Workspace, store files, run a command, and inspect its attempt.

Use a Workspace when work needs durable files and retained Run history.

## Create and enter a Workspace

```bash theme={null}
idyl workspace create <workspace> --namespace <namespace>
idyl use <namespace>/<workspace>
```

## Store files

```bash theme={null}
idyl file put src/main.py ./main.py
idyl file list
idyl file get src/main.py --to ./downloaded-main.py
```

Workspace paths are relative. A single file can contain up to 1 MiB, and the
initial Workspace file set can retain up to 16 MiB of live content.

## Create a Run

```bash theme={null}
idyl run create --image python:3.13 -- python /workspace/src/main.py
```

The Run captures the current file revision and queues an attempt. Use the
returned Run ID to inspect or control it:

```bash theme={null}
idyl run get <run-id>
idyl run logs <run-id>
idyl run shell <run-id>
idyl run stop <run-id>
idyl run resume <run-id>
```

`stop` and `resume` preserve the Run ID and captured input revision. A resumed
Run records another Workload attempt.

## Return to Namespace scope

```bash theme={null}
idyl use <namespace>
```

Direct Workload commands such as `idyl deploy` and `idyl create pod` use the
Namespace and do not require a Workspace.