n8500x/atlas-ts repository overview

⁠Atlas on-prem kit

Everything needed to stand up and test the two Atlas images on an on-prem Linux host, with nothing downloaded at run time.

The kit is baked into the atlas-ts image, so the kit always matches the image version it came from (see VERSION).

docker pull <registry>/atlas-ts:<tag>
docker run --rm <registry>/atlas-ts:<tag> kit | tar -x      # → ./onprem
cd onprem && make help

⁠1. Requirements

make doctor checks all of this.

⁠2. Quick start

# 1. images: from the internal registry …
make pull REGISTRY=nexus.internal:8443/n8500x          # or put REGISTRY in local.mk
#    … or from a tarball carried across the air gap
make load FILE=atlas-images-20261104-120000.tar.gz

# 2. preflight + offline tests (no gateway, no LLM)
make doctor
make smoke                 # sandbox + deep agent + service, ~3–5 min
make itest                 # sandbox ↔ Postgres / MariaDB / Redis, ~3 min (pull-itest first if needed)

# 3. the real model
make env                   # creates gateway.env from the template; edit it
make gateway-check         # token, chat, tool calling
make e2e                   # deep agent DevOps task + service, real model, ~5–20 min

Every test target exits non-zero on failure and writes JUnit XML to reports/.

⁠3. Targets

• a fake OAuth-protected MCP server ← the mcp-hub (config and secret rendered from env, like Vault) ← the sandbox ← the agent and the mcp CLI;

• token minted, tools discovered;

• read runs, DELETE held;

• the secret is invisible to commands. | | smoke-openshift | – | The smoke tests with every container as a random UID in group 0, the way OpenShift runs them | | itest | – | The sandbox's DB tooling against real databases, ITEST_DBS="postgres mariadb redis" by default | | itest-all · itest-<db> | – | Adds MongoDB, SQL Server and Oracle Free · one database (make itest-oracle) | | itest-env | – | Creates itest.env for your own database servers (ITEST_EXTERNAL=mssql …) | | mcp-env · mcp-check · mcp-restart | – | Your MCP servers:

• mcp-env creates mcp.env;

• mcp-check shows status, auth, every tool and its approval decision (SERVER= TOOL= ARGS= calls one), and exits 1 if a server is unreachable;

• mcp-restart re-reads the configuration. | | gateway-check | ✓ | Config resolves, token minted, chat completion, tool calling through the deep agent's own client | | e2e | ✓ | gateway-check + e2e-deep + e2e-service | | e2e-deep | ✓ | The deep agent does a DevOps task unattended (Python module + pytest, Dockerfile + hadolint, Kubernetes manifest, git commit, git push). The harness then re-checks every result itself and never trusts the agent's report. | | e2e-full | ✓ | e2e-deep plus a Postgres table and a PySpark JDBC job | | e2e-service | ✓ | The chapter 19 API with the real model | | test · test-all | – / ✓ | smoke itest · everything (make -k test-all keeps going after a failure) | | run TASK="…" | ✓ | Uses the deep agent: asks on the terminal before risky commands | | run-unattended TASK="…" | ✓ | Same, never asks: risky commands are refused and listed in the report | | service-up · service-down | ✓ | Runs the chapter 19 API on 127.0.0.1:8000 (ATLAS_API_BIND, ATLAS_API_PORT) | | oc-deploy · oc-smoke · oc-e2e · oc-run · oc-status · oc-delete | – / ✓ | Deploy to OpenShift / Kubernetes and run the suites or the agent as in-cluster Jobs (section 7) |

KEEP=1 leaves the test databases running after itest / e2e-full, for debugging.

⁠4. What the tests prove

smoke-sandbox runs every check through the sandbox's HTTP API, which is the same path the agent uses:

• /health answers and every required tool is present. Optional tools (Go, AWS CLI, SQLcl, mongosh) are reported if missing.
• 401 without a token or with a wrong one. Commands run as a non-root user, the root filesystem is read-only, and the server's token is not visible to commands. /workspace and /tmp are writable.
• The Linux userland works: grep, sed, gawk, find, xargs, sort, uniq, cut, tr in one pipeline.
• Python: psycopg, SQLAlchemy, oracledb, PyMySQL, pymssql, pyodbc, pymongo, redis, pandas, pyarrow, duckdb, PyYAML, requests, boto3, kubernetes and Jinja2 import; DuckDB runs a query; pytest runs a test.
• Node: pg, mysql2, oracledb, mssql, mongodb, redis, ioredis and knex resolve; better-sqlite3 runs a query.
• Java: a single-file program runs, every JDBC driver loads (PostgreSQL, Oracle, MariaDB, SQL Server, SQLite, H2), and H2 and SQLite answer queries. Maven and Gradle start.
• Spark: a local PySpark job computes a sum and reads a table over JDBC through the bundled drivers.
• DB command-line clients start. A file uploads and downloads byte for byte. A timed-out command is killed.
• The richer API works:
  • a background python -m http.server is started, curled, then stopped as a whole process group;
  • streaming exec and per-command env work;
  • a directory makes a tar.gz round trip, and list/move/delete work;
  • /metrics and /openapi.json are served.

itest: for every database the same matrix runs inside the sandbox.

Your own database servers instead of containers. Use this per database, e.g. when your registry has no SQL Server image (mcr.microsoft.com is not proxied).

1. Run make itest-env and fill in itest.env.
2. List those databases in ITEST_EXTERNAL: the others still run as throwaway containers, and the external ones are neither pulled nor started.

make itest ITEST_DBS="postgres mariadb redis mssql" ITEST_EXTERNAL=mssql
# or for good, in local.mk:   ITEST_EXTERNAL := mssql

MSSQL_HOST=sqlserver01.internal
MSSQL_PORT=1433
MSSQL_USER=atlas_itest
MSSQL_PASSWORD=…
MSSQL_DB=tempdb        # default: the scratch table never lands in a real database, and it is dropped at the end
# also PG_*, MARIADB_*, REDIS_HOST/PORT, MONGO_URI, ORACLE_* (see itest.env.example)

EXTERNAL=1 treats every database in ITEST_DBS as yours. The login only needs to create and drop a table in the target database.

Or put the SQL Server image into a hosted repository of your Nexus. Keep it private: the image is Microsoft's, under its EULA.

docker pull mcr.microsoft.com/mssql/server:2022-latest        # on a machine that can reach mcr.microsoft.com
docker tag  mcr.microsoft.com/mssql/server:2022-latest nexus.internal:8443/mssql/server:2022-latest
docker push nexus.internal:8443/mssql/server:2022-latest
# local.mk:  MSSQL_IMAGE := nexus.internal:8443/mssql/server:2022-latest

The sandbox reaches them over the egress network, so your firewall must allow that route.

e2e-deep checks the result, not the agent's claims. After the agent's report it runs:

• pytest again;
• divide(1, 0) (it must raise ValueError);
• hadolint;
• yq on the manifest (it must be a Deployment named calc with 2 replicas).

It then checks the git commit contents, that git push was held for approval and never run, and that no command hit the deny list. A small model can pass some checks and fail others; the per-check output shows which.

⁠5. Configuration

local.mk (site settings, read by the Makefile):

REGISTRY := nexus.internal:8443/n8500x    # where the Atlas images live
TAG      := 20261104-120000               # default: the kit's VERSION
MIRROR   := nexus.internal:8443/          # prefix for postgres/mariadb/redis/mongo/mssql/oracle test images
DOCKER   := docker                        # or podman
ITEST_DBS := postgres oracle

You can also override individual images: PG_IMAGE, MARIADB_IMAGE, REDIS_IMAGE, MONGO_IMAGE, MSSQL_IMAGE, ORACLE_IMAGE.

gateway.env (make env): Atlas calls the LLM exactly the way the n8500x/claude-code image does. It uses the same variables with the same defaults, so the same env file works for both:

The image's Bedrock mode (direct SigV4, no gateway) is not used on-prem and is not implemented in Atlas.

Corporate CA: put the PEM in certs/ and set CLAUDE_CA_CERT=/certs/ca.pem.

Proxy: HTTPS_PROXY / NO_PROXY in gateway.env (the gateway client honours them).

Giving the sandbox credentials (kubeconfig, cloud profile, …):

1. Mount them in compose.yaml under sandbox.volumes. There is a commented example.
2. Name the variables in SANDBOX_PASS_ENV (for example SANDBOX_PASS_ENV=KUBECONFIG,AWS_PROFILE in .env, through local.mk).

The sandbox scrubs every other variable from commands. The agent container never holds these credentials.

⁠6. MCP servers

The deep agent uses your MCP servers (SQL Server, Jira, Confluence, …) through the sandbox. The sandbox is the box with network access to your systems, and the agent container only talks to the LLM gateway.

agent ──tools mcp__<server>__<tool>──▶ sandbox ──▶ mcp-hub ──HTTP (+ OAuth token)──▶ your MCP server
                     sandbox commands: mcp servers · mcp tools <server> · mcp call <server> <tool> '{json}'

Separate hub container. mcp-hub is a separate container, started from the same sandbox image (docker run IMAGE mcp-hub). It is the only place the MCP configuration and secrets live. The agent's commands run in the sandbox container, so they cannot read the hub's environment. smoke-mcp proves this on every run.

Discovery. At the start of every run the agent asks the sandbox which servers and tools exist. Each tool becomes mcp__<server>__<tool>, with the server's own description and input schema. A server that is down is reported and skipped.

Configuration (mcp.env here; your Vault injector in production). Use any of three shapes; they merge:

• ${VAR} / ${VAR:-default} is rendered from the hub's environment at start-up. A missing variable marks only that server as failed.
• make mcp-restart re-reads the configuration.

Auth per server is optional:

• none;
• oauth2 client credentials: the hub mints the token, renews it before expiry and re-mints on 401;
• bearer (a static token);
• gateway (the same SSO client as the LLM gateway, from GATEWAY_TOKEN_URL/_CLIENT_ID/_CLIENT_SECRET in the hub's env).

Extra headers are allowed. Secrets never appear in an API reply, a log line or a command's environment.

Approval policy per MCP call, decided in the agent before the call leaves it. The hub also enforces deny itself, for every caller. In order:

1. deny globs → never.
2. Arguments the shell policy would deny (e.g. rm -rf /) → never.
3. ask globs → approval.
4. SQL that writes in any argument (INSERT/UPDATE/DELETE/DDL/GRANT/EXEC sp_…) → approval. This applies even to allowed tools; set "sql_writes": "allow" to permit it.
5. allow globs → runs.
6. Tools annotated readOnlyHint → run; destructiveHint → approval.
7. Anything else → the server's default (default ask).

Unattended runs refuse "ask". Set allow globs for your read tools: ATLAS_MCP_MSSQL_POLICY_ALLOW=query,list_*,describe_*. make mcp-check prints the decision for every tool, so you can tune it before a run.

From scripts inside the sandbox:

• mcp call mssql query '{"sql":"select top 5 * from dbo.orders"}', or POST http://127.0.0.1:8080/mcp-servers/<server>/tools/<tool> with {"arguments":{…}} (loopback needs no token);
• the official SDKs are installed for direct use: Python mcp, Node @modelcontextprotocol/client.

OpenShift: the hub is a sidecar in the sandbox pod, listening on 127.0.0.1:8081. Point the Vault injector at the mcp-hub container, or let make oc-deploy create secret atlas-mcp from mcp.env. make oc-mcp-check runs the check in the cluster.

⁠7. OpenShift

Both images run unchanged under OpenShift's default restricted-v2 SCC.

Random UID. OpenShift starts containers as an assigned UID in group 0, not the image's user, and the images are built for that:

• numeric USER (10001 / 1000) with primary group 0;
• every writable path (/workspace, /home/sandbox, /conversation_history, /data, /home/node) is group 0 with group = owner permissions;
• HOME is set explicitly.
• The sandbox gives the unknown UID a passwd entry at start-up through nss_wrapper, so ssh, git and whoami work even with a read-only root.

Restrictions: no root, no capabilities, no privilege escalation, a read-only root filesystem, and ports 8080 / 8000.

Proven by the kit: make smoke-openshift runs every smoke test with all containers as UID 1000680000:0 (OCP_UID), read-only and capability-free.

Deploying (oc logged in to the target project; OC=kubectl works for plain Kubernetes):

make oc-deploy                 # secret from .sandbox-token, sandbox Deployment + Service + NetworkPolicy + PVC
make oc-smoke                  # the offline smoke suites as a Job in the cluster
make env && make oc-deploy SERVICE=1   # + gateway secret (from gateway.env), API Deployment + Service + Route
make oc-e2e SERVICE=1          # real-model e2e as a Job
make oc-run TASK="…"           # the deep agent, unattended, as a Job
make oc-status / oc-delete     # KEEP_PVC=1 keeps the volumes

The manifests in openshift/ are plain Kubernetes YAML: no runAsUser, RuntimeDefault seccomp, a read-only root, all capabilities dropped. A NetworkPolicy lets only pods labelled atlas.io/sandbox-client=true (the agent and test Jobs) reach the sandbox. Images come from $(REGISTRY); point it at the cluster's mirror. For a corporate CA, put it in certs/ca.pem: it becomes secret atlas-ca, mounted at /certs. On plain Kubernetes, add fsGroup: 10001 to the sandbox pod so its PVC is writable.

⁠8. Security model

• Two containers:
  • The agent (model access, approval policy) and the sandbox (commands) only meet on an internal network.
  • The sandbox has no published port.
  • Both run read-only, with all capabilities dropped and no-new-privileges. The sandbox runs as uid 10001.
• Approval policy (in the agent, before a command leaves it):

  • Denied always: wiping / or $HOME, disk writes, fork bombs, reverse shells, reading credential files, dumping the environment, deleting core namespaces.

  • Needs approval: terraform apply/destroy, kubectl apply/delete/…, helm install/upgrade, mutating AWS calls, git push, gh changes, registry push, curl | sh, ansible-playbook without --check, ssh/scp/rsync, systemctl stop, package publishing, and any database write:

    • SQL that writes (INSERT/UPDATE/DELETE/MERGE/COPY, DDL, GRANT, EXEC sp_…) through any client in the image, judged on the whole command line (heredocs and multi-statement strings included);
    • mongosh and redis-cli writes, and bcp in;
    • inline code (python -c, node -e) that uses a DB driver to write;
    • .sql files and scripts the command runs, which the agent fetches from the sandbox and checks before running (a DB driver plus a write, or a Spark JDBC write).

    The patterns catch mistakes, not a determined adversary. The real boundary for direct database access is a read-only login for the sandbox; let writes go through an MCP server, where the same SQL check and your MCP server's permissions apply.

  • Dry runs are allowed.

  • The sandbox enforces the never-allowed list itself for every caller, and the whole policy on its own MCP endpoint (/mcp), where no agent sits in front.

  • Each && / ; part of a command is judged separately.

• Sandbox API:
  • bearer token (generated by make into .sandbox-token, mode 600);
  • per-command timeout with a process-group kill;
  • output, concurrency and timeout caps;
  • one JSON audit line per command (make logs S=sandbox).
• The test databases use throwaway credentials and live only on the internal network, with their data in tmpfs.

⁠9. Reports and CI

Each suite writes reports/<suite>.xml (JUnit). A Jenkins stage example:

stage('Atlas on-prem tests') {
  steps {
    sh 'docker run --rm $REGISTRY/atlas-ts:$TAG kit | tar -x'
    dir('onprem') {
      sh 'make REGISTRY=$REGISTRY TAG=$TAG doctor smoke itest'
      withCredentials([file(credentialsId: 'atlas-gateway-env', variable: 'GW')]) {
        sh 'cp "$GW" gateway.env && make REGISTRY=$REGISTRY TAG=$TAG e2e'
      }
    }
  }
  post { always { junit 'onprem/reports/*.xml'; dir('onprem') { sh 'make clean || true' } } }
}

⁠10. Troubleshooting

⁠11. Files