Set up Developer Preview 0.1.0

This guide is for the exact published Windows/Linux packages in 0.1.0-developer-preview. A local AI agent is optional; it needs terminal access on your computer. Instructions do not install a Skill, accept an agreement or authorize a download. First personally accept the applicable terms and download the package on Downloads. Do not put secrets in an assistant chat.

Verify first, then extract

Read the versioned SHA256SUMS over verified HTTPS. Match the filename, size and full SHA-256 before running any packaged executable. The plain Windows prompt and plain Linux prompt pin the same values.

Windows can use Get-FileHash -LiteralPath <archive-path> -Algorithm SHA256; Linux can use sha256sum <archive-path> with the actual safely quoted path. Stop on mismatch. Extract the entire verified archive into a new user-owned directory, with a safe archive tool that rejects traversal/unsafe links, keeps Linux executable bits and valid in-tree links, and overwrites no existing files. On Linux, run sha256sum --check bundle-manifest.sha256 from that extracted root. Keep program files separate from instance data. Do not merge into an old install.

Host prerequisites and boundaries

Use a normal non-elevated owner on Windows, a non-root owner on Linux. No development SDK, Docker, separate .NET runtime or system PostgreSQL installation is required: the package contains its product runtime and PostgreSQL 16.15. Windows also has app-local ICU/CRT dependencies. Inspect actual OS/architecture before execution.

Linux’s bundled PostgreSQL metadata records a glibc 2.36 baseline; inspect actual dynamic library availability for the packaged apphost and PostgreSQL using existing host tools such as ldd. That baseline alone does not prove all product libraries are present. Do not guess a universal apt/dnf dependency list. Explain a missing library and obtain specific consent before a system package installation.

Windows native Studio additionally requires host-installed Microsoft Edge WebView2 Evergreen. Linux native Studio requires a graphical session, GTK 3 and WebKitGTK 4.1 (2.40 or later). No desktop, trust-store change or runtime is installed silently. Headless CLI/Server setup does not require a desktop. Recorded Linux lifecycle evidence covers Fedora 44, Ubuntu 26.04.1 and Debian 13.7; WSL and other host versions must not be described as covered by that matrix. Windows native and hosted CLI evidence have their separate published boundaries.

A new instance, not the default

Choose a unique absolute instance path below your own user state directory and a unique client connection name. Check that neither already exists. Do not use the launcher that chooses the default instance for this isolated setup. If owner-only protection fails, stop and explain; do not weaken ACLs or permissions to continue. If an existing CLI profile document is reported malformed, preserve it and stop for owner assessment; do not overwrite/reset other connections to finish setup.

The following variables stand for your selected paths, not paths to copy literally. In Windows PowerShell:

$Bundle = (Resolve-Path -LiteralPath 'YOUR_NEW_EXTRACTED_DIRECTORY').Path
$Instance = Join-Path $env:LOCALAPPDATA 'axoldb\instances\YOUR_UNIQUE_NAME'
$Axol = Join-Path $Bundle 'bin\axol.exe'
& $Axol --help
& $Axol --local server status --bundle-root $Bundle --instance-root $Instance --output json
& $Axol --local server start --bundle-root $Bundle --instance-root $Instance --output json
& $Axol --local server trust --bundle-root $Bundle --instance-root $Instance --output json
$Config = Get-Content -LiteralPath (Join-Path $Instance 'config\server.json') -Raw | ConvertFrom-Json
$Endpoint = "https://localhost:$($Config.publicHttpsPort)"

On Linux, set bundle to the new extracted root, instance to the new state path, then use:

axol="$bundle/bin/axol"
"$axol" --help
"$axol" --local server status --bundle-root "$bundle" --instance-root "$instance" --output json
"$axol" --local server start --bundle-root "$bundle" --instance-root "$instance" --output json
"$axol" --local server trust --bundle-root "$bundle" --instance-root "$instance" --output json

Start only if status confirms this intended instance is not already running. AXOL-SERVER-ALREADY-RUNNING is not a new initialization or permission to stop another instance. Get the actual numeric publicHttpsPort from the non-secret config/server.json, and set endpoint="https://localhost:$port" using that value. Keep both listeners loopback-only; no firewall or public-port changes are needed. Record the instance ID; never publish secrets/, private TLS keys or logs wholesale.

Strict TLS connection and private bootstrap

After checking connection add --help, choose a new profile name, e.g. a unique setup-... name. The public CA path reported by server trust is also <instance>/trust/axoldb-instance-ca.crt. Supply it explicitly with --ca-file; do not disable hostname/chain validation or silently modify an OS trust store.

& $Axol connection add $Profile --endpoint $Endpoint --ca-file (Join-Path $Instance 'trust\axoldb-instance-ca.crt') --output json

"$axol" connection add "$profile" --endpoint "$endpoint" --ca-file "$instance/trust/axoldb-instance-ca.crt" --output json

Private human step: an assistant whose terminal output is captured must not run the assertion reveal there. Give the user these exact commands with the resolved non-secret paths/profile and a fresh UUID request ID. In a private, unrecorded interactive terminal on the Server host, the user runs the local reveal, then pastes the assertion into bootstrap’s hidden terminal input, never a command argument or chat. Bootstrap stores its returned credential in that profile and prints only safe metadata.

# User's private interactive terminal only; keep $RequestId for outcome recovery.
& $Axol --local server bootstrap-assertion --bundle-root $Bundle --instance-root $Instance --reveal
& $Axol credential bootstrap --connection $Profile --request-id $RequestId --principal "setup/$Profile" --output json

# User's private interactive terminal only; keep $request_id for outcome recovery.
"$axol" --local server bootstrap-assertion --bundle-root "$bundle" --instance-root "$instance" --reveal
"$axol" credential bootstrap --connection "$profile" --request-id "$request_id" --principal "setup/$profile" --output json

Choose the UUID once before these commands ([guid]::NewGuid() in PowerShell, or the existing Linux /proc/sys/kernel/random/uuid source). Preserve it on an uncertain outcome. Inspect credential resolve-bootstrap --help and follow the original request/hash outcome workflow; do not blindly mint a new request or regenerate a consumed assertion. If native first-run setup already owns the pending delivery, use that documented UI/recovery flow instead of mixing the two.

Prove authenticated public reading

After the private step, the assistant can resume with non-secret checks:

& $Axol credential list --connection $Profile --output json
& $Axol connection test $Profile --output json

"$axol" credential list --connection "$profile" --output json
"$axol" connection test "$profile" --output json

Require a successful own-credential metadata read over the named HTTPS connection, and authentication: succeeded in the connection test. Ready, liveness, --local reads and a friendly profile name alone are insufficient. This does not require creating a Population, granting broader authority or accessing internal PostgreSQL.

Open Studio when available

For the same instance, use axol --local studio --bundle-root <bundle> --instance-root <instance> with the actual executable/paths above. Do not launch the default-instance shortcut. Without suitable GUI/session/libraries, finish the CLI checks and record Studio not opened. Do not install a desktop or widen X/Wayland permissions automatically.

The CLI credential store and Studio’s in-memory/optional encrypted vault are separate. For this CLI-first setup, if Studio needs a credential, inspect credential issue --help: the owner may issue an additional credential with a fresh --request-id, --connection <profile> and --credential-out <new-owner-private-file>. Do not use --credential-stdout. The command creates protected output without overwriting a file; it does not populate Studio automatically. The human reads that file privately and supplies the credential in Studio’s connection UI for the actual localhost endpoint. Never send its contents through the assistant transcript. Only claim GUI connection/read success when observed; otherwise record that exact human step as pending and retain the independently verified CLI result.

Handoff and safe stop

Report install path, exact instance root/ID, endpoint, profile, actual authenticated read and pending human actions. Record same-root server start/server status commands for reuse. Closing Studio leaves Server running. Graceful shutdown:

& $Axol --local server stop --bundle-root $Bundle --instance-root $Instance --output json

"$axol" --local server stop --bundle-root "$bundle" --instance-root "$instance" --output json

Verify the resulting status. Never delete data, kill arbitrary PIDs, reinitialize an existing cluster or stop another instance as a setup shortcut. A later start must use the same compatible bundle/instance; expired credentials need the documented credential workflow, not data deletion. Read operations and limitations. The Operator Skill is optional guidance, not a prerequisite or evidence of compatibility with every agent.