# Machines: Cloud Development Environments
> Part of the NocoDB documentation (Agents). Index of all pages: https://nocodb.com/llms.txt. Any docs page is available as Markdown by adding `.md` to its URL.
URL: https://nocodb.com/docs/agents/machines
Last updated: 2026-10-29
Set up the cloud development environment of a NocoDB coding agent: packages, a setup script, environment variables and secrets, preview port and size.
A machine is the cloud development environment of a NocoDB coding agent: the computer that each coding session runs on. It has the languages, databases and tools that your code needs to build and run its tests. Every session starts on a fresh copy of a machine, so sessions do not affect each other. New sessions use the **Default** machine of the agent.
## Before you begin
* To create, change, build or delete machines, you need the **Creator** role or higher in the project. Members with the **Editor** role can see the machines and pick one for a session. NocoDB shows them **Only Creators can create, edit or build machines.**
* To build a machine, the workspace must have [credits](/docs/product/workspaces/credits).
## The base machine
Every machine builds on the **Base machine**. The base machine runs Ubuntu 22.04 with a desktop. It has these tools:
* Node.js 24
* Python 3
* git
* GitHub CLI
* ripgrep
* Chrome
A session with no machine of its own runs on the base machine.
When you [set up a coding agent](/docs/agents/coding-agent#set-up-a-coding-agent), NocoDB creates a machine for the default repository. It adds the tools that it finds in the repository and builds the machine before the first run.
## An ephemeral environment for every run
A NocoDB coding agent machine gives each run an ephemeral environment. Each run starts on a fresh copy of the machine, so runs do not affect each other. The copy is an isolated cloud sandbox: sessions do not share files or processes. See [Security](/docs/agents/security).
The cloud dev environment of a session stops when it is idle, and the session keeps its work. When you archive a session, NocoDB releases its machine and stores its work. See [Stop when idle](#stop-when-idle).
## Open the machines of an agent
The machines of a coding agent are in its settings.
1. Open the coding agent.
2. In the top bar, click **Settings**.
3. Go to **Machines**.
The **Machines** section shows the selected machine and its settings. Use the menu at the top to select another machine. Click **Versions and packages** to open the machine page, with the tabs **Overview**, **Versions** and **Build log**.
## Create a machine
A coding agent can have more than one machine.
1. In the **Machines** section, open the machine menu.
2. Click **New machine**.
3. Type a **Name**.
4. In **Copy packages from**, select a machine to start from. To start empty, select **None**. You then pick the packages after you create the machine.
5. Click **Create machine**.
6. Pick the packages.
7. Build the first version. See [Pick packages and build](#pick-packages-and-build).
Until you build its first version, a machine shows **Not built yet**, and sessions on it use the base machine.
To make a machine the default:
1. Open **More actions**.
2. Click **Make default**. New sessions then start on the machine.
You can also rename and delete a machine from the **More actions** menu.
## Pick packages and build
You pick the packages of a machine on the machine page. Then you build a new version of the machine.
1. Open the machine page.
2. Open the tab for the new version, for example **Build first version** or **New version**.
3. Turn on the packages that the machine needs. Search the catalog, or browse its tabs: **Languages**, **Package managers**, **Services**, **Tools**, **Extra packages** and **Commands**.
4. For a language, select a version.
5. Click **Build** and the version, for example **Build v2**.
Until you build it, the new version is a draft. The footer shows the changes from the version in use, for example **Draft v2: 1 change from v1, not built**. The tab shows **Continue v2 draft**. To drop the changes, click **Discard changes**.
Builds take a few minutes. You can continue to work. Sessions stay on the current version until the new version is ready. When the build is ready, new sessions use it.
The catalog has these packages:
| Category | Packages |
| -------------------- | ---------------------------------------------------------------- |
| **Languages** | Node.js, Python, Go, Rust, Java, Ruby, PHP, .NET, Bun, Deno |
| **Package managers** | pnpm, Yarn, uv, Poetry |
| **Services** | PostgreSQL, MySQL, Redis, MongoDB |
| **Tools** | Docker, Playwright browsers, ffmpeg, AWS CLI, Terraform, kubectl |
A **Detected** tag marks the packages that NocoDB found in the repository, for example from `package.json`, `.nvmrc`, `pyproject.toml`, `go.mod` or `docker-compose.yml`.
### Extra packages
For anything that is not in the catalog, add it by name under **Extra packages**:
| Field | Installs with |
| ---------------- | ---------------- |
| **System (apt)** | `apt` |
| **Global npm** | `npm install -g` |
| **Global pip** | `pip install` |
Type the package name. Then press **Enter**.
### Services
A service, for example PostgreSQL or Redis, starts with every session. The agent gets its connection details as environment variables, so tests and dev servers connect without setup. For example, PostgreSQL sets `DATABASE_URL`, and Redis sets `REDIS_URL`.
## Setup script
The **Setup script** runs as root when the machine is built, after the packages. Use it for steps that the catalog does not cover, for example to install a tool from its own installer. Write one command per line.
A command that fails makes the build fail. NocoDB caches the result, so the script does not run again in each session.
To save a change, click **Save and rebuild**.
## Environment and secrets
**Environment and secrets** are environment variables that NocoDB sets on the machine of every session, for example an API key for a test service.
1. In **Environment and secrets**, click **Add variable**.
2. Type the name, for example `STRIPE_TEST_KEY`. Use letters, digits and underscores. The name cannot start with a digit.
3. Type the value.
4. Click **Add**, or press **Enter**. NocoDB saves the variable.
The values reach the machine only, never the chat. NocoDB hides the values in the command output and the files that the agent reads.
New sessions get the changes.
Do not add production secrets. Use test keys and credentials with the lowest access that the agent needs. Anyone who can run a session on this agent can read these values, for example in the terminal.
A machine can have up to 50 variables.
## Preview port
**Preview port** sets the port that the **Preview** pane of a session opens. Leave it empty to open the first port that the app listens on. Type a port from 1 to 65535 to open that port.
## Stop when idle
**Stop when idle** sets how long the machine of a session stays up after the last reply of the agent. Select 10, 15 or 30 minutes, or 1 hour. The default is 30 minutes.
When the machine stops, the session keeps its work. The machine starts again when you send a message.
## Machine size
**Machine size** sets the CPU and memory of the machine:
| Size | CPU | Memory |
| ------------ | ------ | ------ |
| **Small** | 4 vCPU | 4 GB |
| **Standard** | 8 vCPU | 8 GB |
**Standard** is the default. A machine with no size runs at **Standard**. When you change the size of a built machine, NocoDB rebuilds the current version at the new size. Sessions keep the current size until the build is ready.
## Versions
Each build makes a new version of the machine, for example v1, v2 and v3. The **Versions** tab lists every version. New sessions use the version that is in use. A change of the version does not affect sessions that already run.
| Action | Where | What it does |
| ------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Rebuild with updates** | At the top of the **Versions** tab | Builds the packages of the version in use again, as a new version. |
| **Use this version** | On a version that is ready | New sessions use this version. |
| **New version from this** | In the menu of a version | Starts a new version with the packages of this version. |
| **View log** | In the menu of a version | Opens the build log of this version. |
| **Cancel build** | On **Overview** and in the **Machines** settings, while a build runs | NocoDB no longer waits for the build, and ignores its result. |
When a build has the same packages and commands as an earlier build, NocoDB reuses that build. The version shows **Reused an identical build**.
When a build fails, the version shows **Build failed**. Open **Build log** to see why. NocoDB can also suggest a fix. Review the fix. Then click **Apply fix and rebuild**. The suggested fix uses AI [credits](/docs/product/workspaces/credits).
When a machine was built on an older base image, it shows **Update available**. New sessions cannot start from it. Click **Upgrade** to rebuild the same packages on the current base image.
## Machine suggestions from a session
When a session needs a tool that the machine does not have, the agent can suggest a change. The session shows a card that asks to add the package or command to the machine for future sessions.
| Member | What happens |
| ------------- | --------------------------------------------------------------------------------------------------------------------- |
| A Creator | Can click **Add and rebuild**. NocoDB builds a new version in the background. The current session continues as it is. |
| Other members | See **Only Creators can change machines. Ask one to apply this.** |
An agent can have no machines yet while its repository needs tools that the base machine does not have. Creators then see **This repository needs tools the base machine doesn't have** on the agent page. Click **Set up machine** to create one.
## Good to know
* A workspace can build up to 3 machines at the same time. Each machine builds one version at a time. A canceled build counts toward this limit for up to 2 hours, because it continues in the background.
* When you delete a machine, NocoDB deletes all its versions. Sessions that already run continue. New sessions use the default machine.
## Related
* [Coding sessions](/docs/agents/coding-sessions)
* [Coding agents](/docs/agents/coding-agent)
* [Security](/docs/agents/security)
---
## Related pages
- [Agents](https://nocodb.com/docs/agents.md): NocoDB agents are AI agents that work in a project: they read and change your tables, documents and code, answer in chat, and run on their own on a trigger.
- [AI Agents](https://nocodb.com/docs/agents/ai-agents.md): NocoDB is a no-code AI agent builder for business: AI agents that work on your tables and documents, answer in chat, and run agentic workflows on triggers.
- [Create an AI Agent](https://nocodb.com/docs/agents/create-agent.md): How to create an AI agent in NocoDB: describe the job in a setup chat or pick a template, then review and turn it on. NocoAI can also build it.
- [AI Agent Use Cases and Templates](https://nocodb.com/docs/agents/use-cases.md): AI agent use cases and examples for sales, customer service, marketing, operations and project management: 13 NocoDB templates to start from.
- [Instructions and Files](https://nocodb.com/docs/agents/instructions.md): Write the instructions of a NocoDB agent as a brief for a teammate, mention tables and documents with @, and attach files that the agent reads on every run.
- [Tools and Access](https://nocodb.com/docs/agents/tools-and-access.md): Set the AI agent tools of a NocoDB agent: what it can read and change in tables, records, documents and the web, its project role and its managed machine.
- [AI Agent Skills](https://nocodb.com/docs/agents/skills.md): Turn on AI agent skills in NocoDB: reusable instructions from the project, workspace or organization catalog that an agent loads when a task needs them.
- [Triggers and Results](https://nocodb.com/docs/agents/triggers.md): Build an AI agent workflow in NocoDB with triggers: a schedule, record changes, comments, forms or webhooks. Send the results to chat, email or Slack.