> ## Documentation Index > Fetch the complete documentation index at: https://docs.2501.ai/llms.txt > Use this file to discover all available pages before exploring further. # Central configurations > Prepare, test and assign a command environment for your agents A Central gives an agent a container with the command-line tools it needs. Each task that uses it gets its own temporary environment, without requiring a Host. ```mermaid theme={null} flowchart LR A[Prepare a manifest] --> B[Save a version] B --> C[Select execution settings] C --> D[Test command execution] D --> E[Assign agents] E --> F[Task starts its own container] ``` ## Choose the right tool | Need | Use | Example | | - | - | - | | Work on a particular machine | [Host](https://docs.2501.ai/0.20/core-concepts/hosts.md) | Inspect a database server's local files | | Run command-line tools in a dedicated environment | Central | Use cloud administration tools | | Call a service's published tools | [Plugin](https://docs.2501.ai/0.20/configure/plugins.md) | Query a ticketing system through MCP | An agent can have a Host, several Centrals and plugins. An agent that uses a Central can also use an HTTP API plugin. Describe each Central's purpose so that the task can choose an appropriate command environment. The [tool selection guide](https://docs.2501.ai/0.20/best-practices/mcp-plugins.md) explains when plugins fit better than shell commands. > [!NOTE] > > Central is off by default. Ask your installation administrator to enable it through [Feature toggles](https://docs.2501.ai/0.20/deployment/feature-toggles.md) and prepare the execution environment. Administrators create configurations, activate versions and run checks. Users and auditors can inspect configurations and results in organizations they can access. ## Create a configuration **1. Open Central** Choose **Add Central** and enter a name and description, such as `Cloud operations` and `Tools for the production cloud account`. **2. Start from an example** Choose **Kubernetes example** or **Swarm example**, or import your YAML or JSON manifest. **3. Choose your image** Use an image containing the required tools, pinned to its immutable SHA-256 digest. **4. Validate the draft** Choose **Validate** and correct any errors reported in the editor. **5. Save the first version** Choose **Create Central**. Saving does not start a container or test its tools. The manifest supports one Kubernetes Pod, one Kubernetes Deployment template or one Compose service. Keep the example's schema declaration and security settings. Multiple containers, custom startup commands, volumes and privileged settings are not supported. Validation checks the configuration format. It does not check registry access, image compatibility or whether commands can run. A manifest must fit within 64 KiB of UTF-8. Keep large scripts and tool files in the container image. The examples request 0.1 CPU core and limit usage to 1 core. Memory requests are 128 MiB and limits are 256 MiB (`128Mi`/`256Mi` on Kubernetes, `128M`/`256M` on Swarm). They run as UID/GID 1000, use a read-only root filesystem and drop all Linux capabilities. Keep these controls when adapting an example. ## Add credentials and packages Use the credential picker to map an environment variable, such as `GITHUB_TOKEN`, to a saved Secret or Vault path, then choose **Add mapping**. The manifest keeps a reference to the credential, not its value. Do not paste tokens into the manifest. For Swarm, the mapping has this shape: ```yaml theme={null} x-2501: schema-version: 1 credentials: GITHUB_TOKEN: credential: REPLACE_WITH_CREDENTIAL_ID ``` 2501 resolves credentials at the task's first Central call and checks access again before delivering them to the container. Revocation blocks delivery. Credential values are redacted from command output. An image can already contain all its tools. Alternatively, declare exact package versions in the manifest; **Additional packages** shows those in the selected version. Packages are installed into temporary storage before task credentials arrive. No new image is published. The image must already contain the matching package manager. Use a prepared image for tools that need installation scripts or system services. Merge the matching fragment into your existing manifest, preserving its image and security settings. This example installs a Python package; choose the exact package and version your tools require. > [tab] Kubernetes > > Add the annotation to the top-level Pod or Deployment metadata: > > ```yaml theme={null} > metadata: > annotations: > 2501.ai/dependencies: '{"python":[{"package":"requests","version":"2.32.3"}]}' > ``` > [tab] Swarm > > For Swarm, add dependencies to the service's x-2501 extension: > > ```yaml theme={null} > x-2501: > schema-version: 1 > dependencies: > system: > - package: jq > version: REPLACE_WITH_EXACT_APT_VERSION > npm: > - package: semver > version: 7.7.2 > python: > - package: requests > version: 2.32.3 > ``` Choose **Validate**, save the version and test it below. For manifests maintained outside the editor, use `x-2501.credentials` on the Compose service, or the JSON `2501.ai/credentials` annotation on Kubernetes metadata. Map each environment name to `{credential: }`. An entire environment value can also be `{secrets.github}` or `{secrets:github}`. These names select the organization credential first, then a tenant credential only when no organization credential exists. A failed organization credential does not fall back. Partial string interpolation is unsupported. Dependencies support `system`, `npm` and `python` lists, each with `package` and an exact `version`. System packages need `apk`, or `apt-get` and `dpkg-deb`; npm packages need npm; Python packages need Python and pip. Installation scripts do not run, and Python packages require compatible wheels. Transitive dependencies resolve again when each container starts. Use a prepared image when you need reproducible dependencies, source builds or install scripts, and provide access to the required package repositories. ## Test and activate a saved version **1. Select the version** Choose a **Saved version** in the action bar. Unsaved manifest edits are not part of the test. **2. Choose where commands run** Leave **Cluster (optional)** at **No cluster (default)** for local execution, or select a configured cluster in the organization. **3. Activate the settings** Choose **Save settings** to use the selected configuration for new tasks. **4. Run the check** In **Dry run**, choose **Test** to test commands in a temporary container and check that it is removed afterwards. The installation supplies the command runtime automatically. You do not need to enter another runtime image. | The check proves | The check does not prove | | - | - | | The selected configuration can start and run the test command | That task credentials can access your external services | | Cleanup was confirmed at the time of the test | That the environment will remain available | The test uses no task credentials. Changing the selected configuration invalidates the previous result. A disabled test explains what is missing. Deployment requirements are separate: [Kubernetes](https://docs.2501.ai/0.20/deployment/kubernetes.md#centrals) and [Docker Swarm](https://docs.2501.ai/0.20/deployment/docker-swarm.md#centrals). To use another namespace in the Engine’s Kubernetes cluster, declare it in the manifest: ```yaml theme={null} metadata: namespace: central-tools annotations: 2501.ai/schema-version: "1" ``` To select an explicit Kubernetes namespace, set top-level `metadata.namespace` in a Pod or Deployment, or `x-2501.namespace` on a Compose service. Outside the configured shared namespace and engine namespace, it needs matching `2501.ai/tenant-id` and `2501.ai/org-id` labels, `pod-security.kubernetes.io/enforce=restricted`, and namespace-read and pod-management permissions. Remote Kubernetes Centrals use verified HTTPS dialback: configure the connection's `dialback_url` or `SATELLITE_DIALBACK_URL` on the engine, plus certificate trust and network access. They do not use local `pods/attach` access. Deploy the engine's multi-architecture image index when Central workloads use a different architecture from the engine. New bundled-runtime sessions resolve the current engine release when they launch; an existing container keeps its runtime, and an explicit runtime-image selection stays pinned. No `CENTRAL_RUNTIME_IMAGE` setting is needed. A dry run returning `409 central_runtime_unavailable` means the bundled runtime could not be resolved; check the engine image and registry access. ## Assign agents Create agents from **Agents** and select their **Centrals**. **Assign to Central** adds an existing agent without removing its other Central assignments. Host-based CSV and JSON exports exclude Central-only agents; manage these assignments in Command Center. A task starts its Central container when it first needs it, then reuses that container. Its selected environment remains fixed for the task, including continuations. Configuration changes apply to new tasks. Create a new task when changing an existing task's command environment. A queued or resumed task fails if its agent's execution target has changed. If the change occurs during job planning, 2501 refuses the planned task and plans the job again. Start a new task for the new target. A task stops if none of the assigned Centrals fits its work. Removing every Central from an agent preserves its Host assignment. With both a Host and Centrals assigned, a task waits for the Host before selecting its environment. It reserves the Host until the task ends. For automated host-based exports, check the `x-export-skipped-rows` response header for excluded Central-only agents. ## Keep versions and resolve failures **Save Changes** creates a new version while preserving earlier versions. **Compare with** shows an older version alongside the editor. **Export** downloads the current editor content. If another administrator saved first, reload the saved version before trying again. > [!WARNING] > > If a command's outcome is unknown, check its effect before trying again. If container termination is unconfirmed, inspect the workload before recording termination evidence in **Maintenance**. ### Execution limits | Limit | Default | | - | - | | Command timeout | 30 seconds | | Session timeout | 30 minutes | | Output per command | 1 MiB | | Output per session | 8 MiB | Output limits measure raw output. Interactive terminals and background jobs are unavailable in Central. Use a Host when the workflow needs those capabilities. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.