Choose Central, shell or a plugin
Use a Host for operations on one machine when its pre-installed CLIs are simple to use and need no additional service authentication. Use Central for commands that operate an external control plane. Within Central, userun_shell for a simple CLI with usable help and no service authentication. Prefer a plugin when the CLI requires authentication, has inadequate help, or is a custom/internal tool. Choose a suitable MCP plugin first; when none covers the required operation, configure an HTTP API plugin with structured requests and API documentation.
A Central agent can also use assigned MCP and HTTP API plugins in the same task. Keep shell commands available for helpers, additional tools and capabilities the plugins do not cover. Each task retains its configured execution target and uses only authorized tools and credentials.
The agent follows these instructions using its task context and tool descriptions; they do not automatically configure or route integrations. The tool selection decision tree shows each branch.
Create a configuration
Enable Central in Settings, then open Central beside Hosts, choose Add Central, and enter a name and description. Import a YAML or JSON manifest, or start from the Kubernetes or Swarm example. Both examples include a Node image pinned by SHA-256 digest. The Kubernetes example needs no namespace: it uses the shared namespace configured by the installation. Choose an image containing the tools your commands need and keep it pinned by digest. The editor displays syntax colors, line numbers and inline errors. Validate manifest checks the supported configuration format; it does not verify registry access or runtime compatibility. Administrators can create and save configurations. Users and auditors can inspect configurations in organizations they can access.Supported manifests
Use one Kubernetes Pod, one Kubernetes Deployment template, or one Compose service for Swarm. Declare Central schema version 1. Kubernetes Pod and Deployment manifests may set top-levelmetadata.namespace for an explicit placement. Compose services may set x-2501.namespace when targeting Kubernetes. When omitted, local execution uses the existing connection placement, then the shared namespace selected by CENTRAL_LOCAL_K8S_NAMESPACE. Without that setting, it falls back to the Engine namespace. A remote connection uses its configured namespace, or the Kubernetes default namespace if none is set. No namespace is required on Swarm. The manifest must fit within 64 KiB of UTF-8. Additional customer containers, custom commands, volumes, privileged settings, YAML aliases, duplicate keys and multiple documents are rejected.
Execution placement
On Kubernetes, the operator chooses a dedicated shared namespace and setsCENTRAL_LOCAL_K8S_NAMESPACE on Engine. Prepare the namespace with restricted Pod admission, scoped Engine Pod permissions and network policies before enabling this setting. Manage them through your deployment system. Engine needs no namespace-read permission for the configured shared placement. Engine attaches through the Kubernetes API; its role needs pods/attach create/get permissions. The reference network policy allows cluster DNS and public destinations, with no incoming connections or access to Engine. The policy blocks connections between Central Pods, including within an organization. Additional policies in this namespace must not grant broad access. The cluster must enforce NetworkPolicy; startup filtering depends on its CNI. Private customer services require an explicit egress exception. Central configurations, credentials and sessions remain scoped to their organization.
For an explicit namespace outside the configured shared namespace and the Engine namespace, the operator must grant Pod access, namespace read permission, matching tenant/org ownership labels and restricted admission. Remote Kubernetes connections use their configured credentials and verified control-plane CA. Network access follows the installation’s existing network controls.
Swarm requires an explicitly configured organization-scoped internal overlay and a controlled proxy with verified HTTPS dial-back. The network must be non-attachable, approved and separate from the product’s infrastructure services. Local discovery needs CENTRAL_LOCAL_SWARM_NETWORK and CENTRAL_LOCAL_SWARM_PROXY; saved connections without a dedicated network are refused at launch too. The deployment does not create the network and proxy automatically. Docker Engine API 1.47 or newer is required. Remote managers and arbitrary worker placement are unsupported. Images declaring Docker volumes are refused before launch.
Resource and security examples
The examples reserve 0.1 CPU core and cap usage at one core. Kubernetes starts with 128Mi requested memory and a 256Mi limit; Swarm uses 128M/256M. Measure your container and commands, then set its memory. Both examples use UID/GID 1000, a read-only root filesystem and drop all Linux capabilities. Kubernetes also prevents privilege escalation and uses the runtime default seccomp profile. Choose an image compatible with these restrictions. Swarm also prevents privilege escalation and accepts the supported subset of these controls; it does not accept arbitrary Compose security options. Saving prepares the configuration. Both cluster types can be selected for execution; launch checks the selected backend and container settings. Task execution enforces the supported security and resource settings.Assign credentials
Enter an environment variable such asGITHUB_TOKEN, choose a saved Secret or Vault path credential, and choose Add mapping. The picker includes credentials from the selected organization and applicable tenant credentials. It writes a credential reference into the draft without reading its value.
For Swarm, the mapping has this shape:
2501.ai/credentials metadata annotation. The Kubernetes and Swarm examples start without credential mappings. Add references with the picker; do not paste a token into the manifest. Runtime-owned variables and variables already holding literal values cannot receive credential assignments.
Credentials are resolved when the task first calls Central. You can also set an entire environment value to {secrets.github} or {secrets:github}. These expressions select the organization credential named github, or the applicable tenant credential if that organization has none. A failed organization credential does not fall back to the tenant credential. Partial string interpolation is not supported. Before delivering the configuration to the connected container, the engine checks the same selected credentials again. Revocation prevents delivery; rotation uses the latest value. Both resolved values are redacted from returned command output.
Version and export
Each save creates an immutable version. Select older versions to inspect or compare their contents. Concurrent changes produce a revision conflict rather than overwriting another administrator’s work; reload the latest saved version before trying again. Import and the Kubernetes/Swarm examples are available only during creation. After creation, edit the manifest directly to save a new version. Import changes the creation draft without saving. Export manifest downloads the content currently in the editor. Neither action activates or executes a configuration.Configure task execution
Turn on theenableCentral feature toggle before configuring execution; it is off by default. enableSatelliteClusters, which adds the Clusters page, is needed only to manage explicit cluster connections; local execution and its dry run work without it.
In Dry run, leave Cluster (optional) on No cluster (default) to test beside the engine without registering a cluster. On Kubernetes this uses the configured shared Central namespace and the Kubernetes attach connection. Without CENTRAL_LOCAL_K8S_NAMESPACE, it uses the Engine namespace. On Swarm the dedicated network and proxy must already be configured. Alternatively, select a registered cluster in the same organization. Central on a remote Kubernetes cluster uses verified HTTPS dial-back, with the configured dial-back URL, certificate trust and egress proxy. Allow that endpoint in the remote cluster’s network policy, mesh and firewall. Remote execution needs Pod management permissions but no Kubernetes attach permission. Choose Save settings to activate the configuration for new tasks. New configurations automatically use the command runtime bundled in the engine image. Engine release images support amd64 and ARM64 through a common multi-architecture index. Deploy that index when Central workloads run on a different architecture from the engine. New sessions and dry runs resolve the current Engine release automatically after an upgrade. A running container keeps the runtime it started with. Explicitly selected runtime images, including older configurations, remain pinned. Short Docker Hub image names are supported.
Choose the saved version in the action bar; it controls both the displayed manifest and the dry-run revision. Declared packages appear under Additional packages without image publishing settings. The installation supplies the command runtime automatically; there is no runtime image to enter in this form. Central does not impose a container-count quota. The cluster schedules concurrent workloads using their declared CPU and memory requirements. If the installation is not ready for Central, saving these settings and testing are disabled with an availability message. Each task captures the selected Central, revision, cluster and runtime selection when it is created. A bundled runtime selection resolves to the current Engine image when its container starts. Configuration changes apply to newly created tasks; continuations retain their original selection.
Choose Test to check command execution in a temporary container. A disabled button explains the missing configuration. The test does not change the agents’ settings or use their credentials. Maintenance is available to administrators for inspecting reservations and confirming cleanup. It stays collapsed during normal use; an unconfirmed container stop displays an alert and opens it.
Choose Assign to Central to add an existing agent, preserving its other Central assignments. Create agents from Agents and choose their Centrals there. A task starts its container only when it first calls Central, reuses it for subsequent commands, and removes its isolated storage when execution ends. Tasks that do not call Central remain unaffected when Central is unavailable.
Host tasks also keep the Host selected when they were created. If you change an agent’s execution target, its queued or resumed tasks fail before executing commands on the new target. Create a new task to use the new target. Saved results remain associated with the original Host; reassignment does not transfer results between Hosts or expose Central results to Host tasks.
If you change an agent’s Host or Central while a job is being planned, the planned task is refused before creation. The job must be planned again for the new target.
A command whose response is lost fails the task. It is not replayed in a replacement container. Command timeout defaults to 30 seconds, session timeout to 30 minutes, command output to 1 MiB and session output to 8 MiB. These output allowances measure raw output. Separate transport ceilings account for JSON escaping and protocol metadata. Interactive terminals and background jobs are unavailable.
Extend a base image
Use an existing image that already contains your tools, or declare pinned packages in the manifest. Central uses that image directly. It installs additional packages into temporary working storage when the container starts, before credentials are delivered. No new customer image is built or published. Additional packages lists the packages in the selected saved revision. There are no builder or publishing settings. Alpine system packages need apk-tools 3 (Alpine 3.23 or newer); Debian/Ubuntu images use apt; npm packages need npm in the image and Python packages need Python and pip. System packages are extracted without running installation scripts. Use an image that already contains a tool when it needs system services or custom installation scripts. For Swarm, add dependencies to the service’s x-2501 extension:Test accessibility
Save the manifest, choose its saved revision and execution settings, then choose Run dry run. The check prepares dependencies, launches a temporary container, connects to its command runtime, runs a fixed command and confirms cleanup. It does not activate the revision or inject task credentials. If the bundled runtime is unavailable, the API returns409 central_runtime_unavailable without reserving a container. A missing revision or local Kubernetes namespace is rejected before a local connection is created.
The panel shows each phase, the last checked time and Commands worked at the last test or a failure. Changing the selected configuration makes the old result inapplicable. A successful check proves command connectivity at that moment, rather than ongoing availability or permissions on an external system. Dry runs are tracked until container termination is confirmed. Users and auditors can inspect results; administrators start checks.
Central tasks do not receive raw saved results from earlier Central sessions. Deadline and output-limit failures stop execution and are reported as those failures; commands are not replayed.
Confirm termination after an uncertain failure
Central tracks running containers and containers whose termination is unconfirmed. The engine records termination after a positive observation. An administrator can also verify termination in the cluster and record evidence against a closed reservation. Host-based CSV/JSON exports exclude Central-only agents and report skipped rows in the response header; CLI resource management also excludes them. Manage Central assignments through Command Center. Host agents retain access to authorized cloud or database CLIs already installed and configured on their Host when no suitable plugin is assigned. Central remains the configuration choice for a new dedicated control-plane command environment.Advanced placement
To use another namespace in the Engine’s Kubernetes cluster, declare it in the manifest:2501.ai/tenant-id and 2501.ai/org-id labels, pod-security.kubernetes.io/enforce=restricted, and permission for the Engine identity to read that namespace and manage its Pods. These requirements apply only outside the configured shared namespace and the Engine namespace. The configured shared placement does not read namespace metadata. A local development kubeconfig cannot authorize execution.
Main Central in the Engine’s own Kubernetes cluster uses the Kubernetes attach API. The control-plane connection must support streaming and authorize pods/attach in the target namespace. No Central-to-Engine URL, session token or dial-back TLS setting is needed. Engine sends configuration and resolved credentials through the attached stream after checking credential access again; they are absent from the Pod specification. A lost stream fails the task without replaying commands or creating a replacement Pod.
Swarm retains HTTPS dial-back. CENTRAL_LOCAL_DIALBACK_URL overrides its endpoint; otherwise it uses SATELLITE_DIALBACK_URL, or API_BASE_URL when there is no separate dial-back TLS listener. For remote Kubernetes clusters, configure dialback_url on the connection or SATELLITE_DIALBACK_URL on Engine, plus certificate trust and any egress proxy. Their Central containers use verified HTTPS dial-back and need network access to that endpoint, with no pods/attach permission. Main Kubernetes Central ignores dial-back settings. Namespace and network approval do not replace application authorization: Centrals and sessions remain scoped to their organization.
For private Engine or customer images, provision image-pull access in the Central namespace. If EXECUTOR_MCP_IMAGE_PULL_SECRET is set on Engine, create the same named secret in the shared namespace. Otherwise, configure the target service account or use the cluster’s node registry access. Other explicit and remote placements need their own pull access. Secrets are not copied across namespaces.
For a private existing image on Swarm, the installation operator can supply its scoped pull credential through the execution API. Pull credentials stay outside the execution container.
The stored credential catalog lists secrets managed by 2501. It does not inventory authentication already configured on a Host, such as a CLI profile, environment or instance role.
Assign Centrals to an agent
Create agents on Agents, then select their Centrals. An agent can use several Centrals from its organization. When a task first runs commands, the engine selects the environment whose image, declared packages and purpose fit the request. The choice and captured execution settings remain fixed for that task, including continuations. A task stops if no configured Central fits. Adding a Central affects new tasks without interrupting existing ones. Removing a Central captured by an earlier task requires a new task. On a Central page, Assign to Central adds an existing agent without removing its other Central assignments. The action bar includes See Agents, Copy ID, saved versions, comparison, reload, export, validation and Save Changes. Saving changes creates another immutable manifest version. Central assignments use the agent page or API (central_ids). The Host-based CSV/JSON format keeps its existing behavior and reports excluded Central-only agents in x-export-skipped-rows.
For an agent with a Host and Centrals, each task selects the Host for machine-local work or a Central for its declared tools. The choice is fixed for that task. Removing every Central is allowed and keeps the Host and credentials. An agent with no command environment can still use plugins; shell commands require assigning a Host or Central.
When Central is disabled or none of the assigned Centrals is activated, the Host remains available. Tasks that use only plugins can proceed without a matching Central. A selector refusal or unavailable selection service keeps the admitted Host; an unassigned ID is refused. Central execution does not receive saved-result labels or raw outputs from Host tasks. Plugin tasks that retain the Host still require its connection. A task with a Host and Centrals waits for that Host to become available before choosing its execution environment; that task keeps the Host reservation until it ends.