Quickstart

This walks the whole loop once: deploy a solver and its data, create a project from it, ask Aura to solve it, and read the result back.

Before you start

You need an Aura API key (sk-aura-…) — nothing here works without one. Mint it in the Aura web app at Settings → API Keys (EU, US), then put it in your environment:

export AURA_API_KEY="sk-aura-..."

Everything below targets the EU deployment, the default. Minted your key in the US app? Pass region="us" (Python) or region: "us" (TypeScript) to the client, or export AURA_REGION=us for the CLI — see Regions.

Keep the key server-side

An API key carries your whole company’s access. Use it from a server, a script, or your own terminal — never from a browser bundle or anything you ship to a client.

1. Install

TypeScript

npm install @strangeworks-inc/strangeworks-aura-sdk

Python

pip install strangeworks-aura-sdk

CLI

npm install -g @strangeworks-inc/strangeworks-aura-cli

2. Deploy your model

A deployment is a solver plus its data, uploaded under a name your company can create projects from.

Its layout is fixed: the solver package goes under run/, the dataset under top-level data/. The solver reads ../data/ at solve time, so the same solver can run against a different dataset.

• Directoryrun/

  • pyproject.toml
  • Directorysrc/

    • Directorysolver/

      • …
• Directorydata/

  • instances.json

See the layout contract for what the server checks.

TypeScript

import { AuraClient, deployFromFolder } from "@strangeworks-inc/strangeworks-aura-sdk";

const aura = new AuraClient({ apiKey: process.env.AURA_API_KEY! });

await aura.createDeployment("vrp");
await deployFromFolder(aura, "vrp", "./my-model/solver", { destPrefix: "run/" });
await deployFromFolder(aura, "vrp", "./my-model/data", { destPrefix: "data/" });

const check = await aura.checkDeployment("vrp");
if (!check.ok) throw new Error(`Not runnable: ${check.missing.join(", ")}`);

Python

import asyncio, os
from aura_sdk import AuraClient, deploy_from_folder

async def main() -> None:
    async with AuraClient(api_key=os.environ["AURA_API_KEY"]) as aura:
        await aura.create_deployment("vrp")
        await deploy_from_folder(aura, "vrp", "./my-model/solver", dest_prefix="run/")
        await deploy_from_folder(aura, "vrp", "./my-model/data", dest_prefix="data/")

        check = await aura.check_deployment("vrp")
        if not check.ok:
            raise RuntimeError(f"Not runnable: {', '.join(check.missing)}")

asyncio.run(main())

CLI

The CLI reads the deployment’s shape from a [tool.aura.deployment.<name>] table in your model folder’s pyproject.toml. aura init scaffolds it:

cd my-model/solver
aura init                 # writes [tool.aura.deployment.<name>]
aura deploy --dry-run     # preview exactly what would upload
aura deploy
aura deployment check

check is the server-side run contract: ok, plus missing and warnings naming what a project created from this deployment would fail on. With the CLI, deploying again syncs — remote files no longer present locally are removed, so renames leave nothing stale. The SDK helpers only upload; see Redeploying is a sync.

3. Create a project and solve

A project created from a deployment lands directly in run mode, so you can chat with it immediately. The deployment is named by its handle, <company>/<name> — the handle field on every deployment response.

TypeScript

const project = await aura.createProject({
  name: "vrp demo",
  fromDeployment: "acme/vrp", // "<company>/<name>"
});

const reply = await aura.chat(project.id, "Solve this and summarize the result.");
console.log(reply.content);

Python

project = await aura.create_project(name="vrp demo", from_deployment="acme/vrp")  # "<company>/<name>"

reply = await aura.chat(project.id, "Solve this and summarize the result.")
print(reply.content)

CLI

aura project create acme/vrp --name "vrp demo"
# → prints the new project id

aura chat --message "Solve this and summarize the result."

Drop --message for the full-screen interactive TUI.

chat() dispatches your message, follows the turn live, and returns the agent’s completed reply. It waits for the reply to your message specifically — see Chat with a project for what that guarantees.

4. Read what the run produced

TypeScript

const [latest] = await aura.listExecutions(project.id);
console.log(latest.status, latest.output_summary);

const solution = await aura.readFile(
  { source: "workspace", projectId: project.id },
  "solutions/out.json",
);
console.log(JSON.parse(solution.text ?? "{}"));

Python

import json
from aura_sdk import WorkspaceFiles

executions = await aura.list_executions(project.id)
latest = executions[0]
print(latest.status, latest.output_summary)

solution = await aura.read_file(
    WorkspaceFiles(project_id=project.id), "solutions/out.json"
)
print(json.loads(solution.text or "{}"))

CLI

aura snapshot list

# "solution" resolves to the path that run recorded
aura snapshot file read <snapshot-id> solution | jq .objective

Each completed solve freezes a snapshot, so this reads the run’s own frozen copy rather than a live workspace a later run may have overwritten.

Where to go next

1. Core concepts — what deployments, projects, conversations and snapshots each own, so the API stops needing guesses.

2. Deploy a model — the config table, the include/exclude rules, and the run/ + data/ contract in full.

3. Instructions and skills — teach the agent your vocabulary, the rules it must not break, and the procedures it should follow.

4. Errors — the three failure modes of a turn, and which one you are looking at.