Getting started

The distribution bundle

The product ships as a signed, air-gapped bundle: atlasberg-proxy-<version>.tar.gz with the container image, a signed JSON manifest, an Ed25519 signature and the static verifier atlasberg-bundle. Verification runs offline, does not depend on a clock, and recomputes the sha256 before checking the signature. Only proceed if the verifier prints an OK line stating the bundle verifies.

Bringing it up with Docker

Load the image with docker load and run the hardened container. No outbound network, read-only root filesystem, memory limits and a single data volume.

• GOMEMLIMIT follows the sizing table in the packaging guide.
• The entire state lives in the atlas-data volume mounted at /app/data: config.db with encrypted secrets, audit trail, anchors, deployment key, admin credential, approval queue and license.
• For a local LLM on the LAN (Ollama or vLLM), remove --network none and configure the provider URL. DLP, guardrails and the audit trail do not change.
• The default database in the image is SQLite.
• The roster is read at boot: after editing the file by hand, restart. The Identity and SSO screen (Settings) edits the same file and applies it live.
• The atlasberg-console-user tool provisions accounts: listar, criar (console access), portal (portal only), senha, console (grant or remove access), remover. The password is read from the terminal without echo, a .bak of the file is preserved and unknown fields in sso.json pass through intact.
• Live console sessions are bound to the person in atlasberg-console-sessions.json (mode 0600) in the data volume; it stores the SHA-256 of the session token, the subject and the expiry, never the token.

First access

The admin credential is generated on first boot and persisted in the data volume. Read it with:

More than one administrator

That generated pair is the break-glass account. The console has a second door: accounts of the local_login.accounts roster in sso.json that carry the console group (local_login.console_group, default atlasberg-console) sign in to the console with their own name. A correct credential without the group receives the same 401 as a wrong password. In the audit trail, an action by a roster account is recorded as local:<username>; the same action by the break-glass pair is recorded as the generic administration session subject.

When a console screen fails

If a console component breaks in the browser, the generic error screen says the screen failed in the browser, not on the server, and shows the error message. It does not show a 500, because a 500 would be a claim about the server.

Tutorial: every AI request of the company through your gateway

For infrastructure. Publish the gateway, register provider keys once, block direct egress, create teams and budgets. About 40 minutes.

docker run -d --name atlasberg --restart unless-stopped \
  --network none \
  --read-only --tmpfs /run --tmpfs /tmp \
  --memory 2g --memory-swap 2g \
  -e GOMEMLIMIT=1750MiB \
  -p 8080:8080 \
  -v atlas-data:/app/data \
  atlasberg-proxy:<version>

docker exec atlasberg cat /app/data/atlasberg-admin-credentials.json

atlasberg-console-user -arquivo /app/data/sso.json criar -usuario maria -nome "Maria"
atlasberg-console-user -arquivo /app/data/sso.json listar

Kubernetes

A Helm chart ships in deploy/helm/atlasberg-proxy with the same hardening: read-only root filesystem, non-root, single volume, and GOMEMLIMIT derived from the memory limit. The chart refuses to install with more than one replica, with a ReadWriteMany volume, or without a memory limit, because the audit trail holds an exclusive single-writer lock.

Health and metrics

• GET /health returns "status":"ok" (plus a components block) when the appliance is healthy.
• GET /metrics exposes the Prometheus metrics; the gateway's own metrics carry the atlasberg_ prefix, alongside the standard Go runtime and process collectors. Push gateway support also exists. See the Protocol page for the full metric list.

curl -s http://localhost:8080/health
# {"status":"ok",...}

Updating

A release update is a new bundle: verify it with atlasberg-bundle, docker load the image and recreate the container over the same atlas-data volume. Back up and restore the whole volume; on restore, events come before anchors. Behavior changes per version are documented for the operator in the release notes shipped with the product.

Turnkey demo

demo/start.sh brings up the gateway plus an OpenAI-compatible mock provider in compose, on an internal network with no internet, with the port published only on 127.0.0.1:8080. It prints the admin credential, the demo virtual key and a self-test. It is a demonstration profile, not production.

Device login: the atlasberg CLI

A developer's terminal, IDE or agent uses the gateway with a personal token instead of a shared key. The atlasberg CLI runs the device login (RFC 8628): it asks the gateway for a code, the person confirms it in the portal, and the terminal receives a token bound to the person and their team. Device login is switched on in Settings, Identity and SSO, Devices tab. Developers install the CLI with npm install -g @atlasberg/cli, download it from the portal under My devices, or receive it through the workstation package.

• Commands: login, env, status, logout, key-helper. Options: -gateway, -nome (device name), -shell.
• The credential is stored with mode 0600 in ~/.config/atlasberg/credenciais.json on Linux, ~/Library/Application Support/atlasberg on macOS and %AppData%\atlasberg on Windows; login never prints it. ATLASBERG_CREDENCIAIS overrides the path; ATLASBERG_SEM_NAVEGADOR suppresses opening the browser.
• atlasberg env prints ATLASBERG_GATEWAY, ANTHROPIC_BASE_URL (<gateway>/anthropic) with ANTHROPIC_AUTH_TOKEN, OPENAI_BASE_URL (<gateway>/openai/v1) with OPENAI_API_KEY, and GOOGLE_GEMINI_BASE_URL (<gateway>/genai) with GEMINI_API_KEY, for posix shells, fish, PowerShell and cmd.
• The appliance serves the binaries itself at GET /api/atlasberg/sso/downloads/{file}: atlasberg-linux-amd64, atlasberg-linux-arm64, atlasberg-darwin-arm64, atlasberg-darwin-amd64 and atlasberg-windows-amd64.exe, from ATLASBERG_DOWNLOADS_DIR (default /app/downloads). The portal's My devices screen links to them and lists the person's tokens for revocation.

Tutorial: sign in from the terminal with SSO

For developers. One command, one code confirmed in the portal, and no key on any laptop.

Tutorial: configure SSO and device login

For administrators. OIDC provider, groups to teams, local accounts, device policy and directory sync.

Tutorial: connect Claude Code, Cursor and SDKs

For developers and workstation admins. The variables each tool reads and the managed settings file for Claude Code.

atlasberg login -gateway https://gateway.example.com
eval "$(atlasberg env)"

Main environment variables

The sso.json file named by ATLASBERG_SSO_CONFIG_FILE also holds local_login (accounts and console_group), device_flow (enabled, token_ttl_hours, code_ttl_minutes, poll_interval_seconds, max_tokens_per_user) and directory_sync. The Identity and SSO screen reads and writes the same file.

• Variable: APP_DIR | What it does: Application directory. The image sets it and the entrypoint passes it through.
• Variable: ATLASBERG_DLP_POLICY_FILE | What it does: Path of the DLP policy file. Default <APP_DIR>/dlp-policies.json. Absent file means factory defaults: mask everything. An invalid file stops the boot.
• Variable: ATLASBERG_APPROVAL_FILE | What it does: Path of the approval queue. Default <APP_DIR>/atlasberg-approvals.json.
• Variable: ATLASBERG_AUDIT_DIR | What it does: Relocates the audit trail to another volume.
• Variable: ATLASBERG_AUDIT_PROFILE=bancario | What it does: Banking profile: hourly anchors plus five year retention.
• Variable: ATLASBERG_AUDIT_RETENTION_DAYS | What it does: Retention window. Cannot go below the legal floor of the banking profile; such a value is refused with an error log.
• Variable: ATLASBERG_AUDIT_ANCHOR_PERIOD / ATLASBERG_AUDIT_ANCHOR_EVERY_EVENTS | What it does: Anchor schedule.
• Variable: ATLASBERG_MAX_CONCURRENT_EXTRACTIONS / ATLASBERG_MAX_PART_BYTES | What it does: File extraction sizing. Invalid values are refused loudly.
• Variable: ATLASBERG_ADMIN_USERNAME / ATLASBERG_ADMIN_PASSWORD / ATLASBERG_SETUP_TOKEN | What it does: Gateway admin credential overrides.
• Variable: ATLASBERG_ENCRYPTION_KEY | What it does: At-rest key of config.db. Without it, virtual keys would sit in the table in the clear.
• Variable: ATLASBERG_IDIOMA_PADRAO | What it does: Default language of console and portal.
• Variable: ATLASBERG_TEMA_PADRAO | What it does: Default theme.
• Variable: ATLASBERG_SSO_CONFIG_FILE | What it does: SSO/OIDC configuration file.
• Variable: ATLASBERG_SSO_CLIENT_SECRET | What it does: OIDC client secret via env indirection.
• Variable: ATLASBERG_PROXIES_CONFIAVEIS | What it does: CIDRs or IPs of the edge. Only when the connection comes from one of them does the gateway read X-Forwarded-For (first untrusted hop, right to left), X-Forwarded-Proto and X-Forwarded-Host. Empty by default, in which case those headers are never read. Helm: identity.trustedProxies.
• Variable: ATLASBERG_DOWNLOADS_DIR | What it does: Directory of the CLI binaries served at /api/atlasberg/sso/downloads. Default /app/downloads.
• Variable: ATLASBERG_TOKENS_PESSOAIS_DIR | What it does: Alternative directory for atlasberg-tokens-pessoais.json, the personal token roster (SHA-256 digests only, mode 0600). Default is the application directory.
• Variable: ATLASBERG_CAMBIO_URL / ATLASBERG_CAMBIO_DESLIGADO | What it does: Source of the USD quote used by the console, or turns the fetch off. Without network this is a normal state.

About Atlasberg Platform

Atlasberg Platform is the control layer between a company and every AI model: each request is authenticated with a virtual key, filtered by policy and DLP, routed to the right provider and written to a hash-chained audit trail. It exposes an OpenAI-compatible API, so applications only swap the base URL.

The same artifact runs in Atlasberg Cloud, in your VPC, on-premises or fully air-gapped, and is priced by capacity and modules, never per seat.

This page is part of the official documentation. To talk to the engineering team, write to [email protected] or use https://atlasberg.com/contato. Answers come within one business day.