> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atonom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Install & connect

> Install the binary supplied by the Atonom team and connect to your environment.

Start with the Atonom CLI binary supplied by the Atonom team, your Atonom environment URL, and an account with permission to edit Lua tools. You do not need a compiler or a copy of the CLI source code.

## Get the CLI

[Contact the Atonom team](/support/index) for the binary that matches your operating system and processor. Follow the installation instructions supplied with your binary, then open a terminal and check:

```sh theme={null}
atonom --version
atonom --help
```

### Install a standalone binary on macOS

If you received a standalone executable named `atonom`, open a terminal in the folder containing it. Install it in your user's bin directory:

```sh theme={null}
mkdir -p "$HOME/.local/bin"
install -m 755 ./atonom "$HOME/.local/bin/atonom"
export PATH="$HOME/.local/bin:$PATH"
atonom --version
```

Add `export PATH="$HOME/.local/bin:$PATH"` to your shell configuration (usually `~/.zshrc` on macOS) to make the command available in new terminals. If macOS prevents the binary from opening, contact the Atonom team for installation assistance.

For other systems, use the instructions included with your supplied binary. To update, request the latest binary from the Atonom team, replace the installed executable, and check `atonom --version` again.

## Create a script workspace

Use a separate directory for the Lua tools you are developing. Replace the example URL before running these commands:

```sh theme={null}
mkdir my-atonom-tools
cd my-atonom-tools
atonom config set base_url https://your-atonom-host.example --local
atonom config show
```

The local setting creates `.atonom/config.toml`. The nearest ancestor containing `.atonom/` becomes the workspace root; scripts default to `.atonom/scripts/` inside it. Run subsequent commands from this workspace or a directory beneath it.

Use a different workspace for each platform environment. Tool IDs and manifest hashes belong to the server from which they were obtained; changing `base_url` does not remap them.

## Sign in

```sh theme={null}
atonom login
atonom status --json
atonom list --json
```

Approve the device code in your browser. For a remote terminal, use `atonom login --no-browser` and open the printed URL yourself. The CLI stores a rotating refresh token in the OS credential store and keeps access tokens in memory. On macOS, the credential store is Keychain.

`status` succeeds when the scripts API accepts your credentials. A successful response with zero scripts is valid. If you receive 401, 403, or 404, follow [Troubleshooting](/atonom-script/cli/troubleshooting).

For automation, inject an authorized token as `ATONOM_TOKEN` using your secret manager. Do not store it in your repository or paste it into an agent prompt. See [Configuration & auth](/atonom-script/cli/configuration).

## Connect the sandbox (optional)

The sandbox lets you test local Lua files with `eval` before saving them to Atonom. If sandbox access is included in your setup, use the sandbox URL and connection instructions supplied by the Atonom team. Replace the example URL below:

```sh theme={null}
atonom config set lua_service_url https://your-sandbox-host.example --local
atonom eval -c 'return { ready = true }' --json
```

Expect `outcome.status` to be `DONE` and `outcome.value.ready` to be `true`. Your Atonom URL and sandbox URL are separate settings; signing in does not automatically configure sandbox access.

Without sandbox access, you can still save and test tools through Atonom using `push` followed by `run --no-save`.

Next: [Build your first Lua tool](/atonom-script/cli/first-tool).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.