Build

An environment is a workspace where an agent or worker can use files, check out repositories, and run commands.

Use an environment when the state of a filesystem matters to the work. Use an ordinary action when the task is a stateless call to a provider.

Workspace or deliverable?

An environment is where work happens. An artifact is a durable output you publish from that work.

A coding agent may clone a repository, change files, and run tests in an environment. The patch, report, or packaged result becomes an artifact when it should survive cleanup or be inspected outside the workspace.

Do not leave the only copy of an important result in an environment that may be destroyed.

Choose who operates the workspace

Both kinds support the same conceptual job. The difference is who owns the underlying machine and lifecycle.

Choose what should reuse the environment

Reuse a workspace when later work benefits from the same checkout, tools, or filesystem state. Common boundaries are one coding agent, one loop family, or one manual diagnostic workspace.

Use a fresh environment when isolation matters more than startup time or when untrusted input could affect the filesystem. Shared state can make repeated work faster, but it also creates coupling that operators must understand.

For repository work, prefer read-only checkout until the process genuinely needs to push changes. Treat code from forks and other untrusted sources as a separate security boundary.

Work with environments in the app

Open Runtime > Environments to create or inspect a workspace. The detail page shows who owns it, whether it is ready, which worker is attached, and which agent or loop uses it.

Commands and logs are diagnostic surfaces. Use them to confirm the workspace state, but do not place long-lived credentials in command text or output.

Provisioning and wake-up can take time. When a run is waiting, check the environment state and worker availability before changing the loop.

Balance reuse, cost, and cleanup

Keeping an environment warm reduces startup time and preserves useful state. Destroying it reduces cost and removes stale files. Choose based on whether future work truly benefits from continuity.

Publish important artifacts before cleanup. The environment's history can explain where work happened, but its files are unavailable after destruction.

Next

• Publish durable files as artifacts.
• Run code in your own infrastructure with workers.
• Use environments from agents and loops.
• Integrate through the Environments API.
• Operate environments from the CLI command reference.