Run nvoken locally

This is the shortest path to seeing nvoken work. It uses official releases, starts a disposable local database, and runs a small TypeScript app through one complete agent turn. You do not need to clone the repository or install Go.

Before you start

You need:

• macOS or Linux with Homebrew
• Docker running
• Node.js 20 or newer with npm
• one active Anthropic or OpenAI API key in your shell
• an exact model ID that key can access
• localhost ports 8080 and 55432 available

The quickstart makes one small model request, which your provider may bill.

1. Start nvoken

Install the matching nvokend service and nvoken client binaries:

brew install deepnoodle-ai/tap/nvoken

Create a clean directory so the generated local secrets stay separate from your application files, then start the quickstart. For OpenAI:

mkdir -p nvoken-quickstart && cd nvoken-quickstart
export OPENAI_API_KEY='<your-provider-key>'
nvokend quickstart --provider openai --model '<model-you-can-access>'

For Anthropic, export ANTHROPIC_API_KEY and use --provider anthropic instead. Leave this terminal running.

nvokend quickstart creates a marked, disposable PostgreSQL 17 container, writes a protected .env, applies database migrations, and starts nvoken at http://localhost:8080. Re-running the command reuses those local resources.

2. Inspect the model catalog

Open a second terminal in the same directory. The generated .env contains the local Runtime credential, so load it and ask nvoken what it advertises:

set -a; . ./.env; set +a
nvoken model list --provider openai
nvoken model get --provider openai --model "$NVOKEN_MODEL"

The catalog is discovery metadata, not an account-access probe. Your provider key, plan, or region may not permit every listed model.

3. Run the TypeScript app

In that second terminal, run the official npm quickstart:

npx --yes --package "@deepnoodle/nvoken@$(nvokend --version)" nvoken-quickstart

It reads only the NVOKEN_* settings from the marked .env, sends one concise prompt, and prints the assistant response. Seeing that response proves the published package discovered the local configuration, admitted durable work, let nvoken execute it, and read the canonical result.

Stop and clean up

Press Ctrl-C in the first terminal, then remove the quickstart database:

nvokend quickstart cleanup

Cleanup removes only the container labeled as owned by this quickstart. The .env remains and contains your provider key plus generated local credentials; delete that file when you no longer want to reuse them.

Build your app next

Install @deepnoodle/nvoken in your TypeScript app and use its Client API. See SDKs & CLI for the packages in every language.

This laptop setup is for evaluation, not production: it has no TLS, backups, supervisor, durable secret store, or high availability. When you are ready to operate nvoken, read Deployment.