Quickstart - Hexel Studio

This quickstart takes you from zero to a running sandbox and a deployed agent. You’ll install a client, authenticate, execute code in an isolated environment, and deploy a Docker image to a permanent endpoint.

Prerequisites

A Hexel Studio account. Sign up at console.hexelstudio.com.
An API key. In the Console, go to IAM → Service Users → Create API Key.
For agent deployment: a Docker image that implements the agent contract.

Set your API key as an environment variable so the SDKs and CLI pick it up automatically:

export HEXEL_API_KEY="YOUR_API_KEY"

In this quickstart you will install a client, authenticate with an API key, run Python code in an isolated sandbox, and deploy a Docker image as a live agent with a permanent URL.

1. Install a client

Python
TypeScript
CLI

pip install hexel

Requires Python 3.10+.

npm install hexel-sdk

Requires Node.js 18+.

curl -fsSL https://hexelstudio.com/install.sh | bash

2. Authenticate

Hexel exchanges your API key for a short-lived token automatically. You only provide the key.

Python
TypeScript
CLI

from hexel import Hexel

client = Hexel(api_key="YOUR_API_KEY")

import { Hexel } from "hexel-sdk";

const client = new Hexel({ apiKey: "YOUR_API_KEY" });

export HEXEL_API_KEY="YOUR_API_KEY"
hexel auth login

For production services, use OAuth client credentials instead of an API key. See Authentication.

3. Run code in a sandbox

A sandbox is an isolated environment you allocate on demand to run code or shell commands. Each sandbox is single-use with a default TTL of 3600 seconds (1 hour).

Python
TypeScript
CLI

sandbox = client.compute.sandbox.create(tier="standard")

result = client.compute.sandbox.execute(
    sandbox["sandbox_id"],
    code="print('Hello from Hexel')",
    language="python",
)
print(result)

client.compute.sandbox.release(sandbox["sandbox_id"])

const sandbox = await client.compute.sandbox.create({ tier: "standard" });

const result = await client.compute.sandbox.execute(sandbox.sandbox_id, {
  code: "print('Hello from Hexel')",
  language: "python",
});
console.log(result);

await client.compute.sandbox.release(sandbox.sandbox_id);

hexel compute sandbox create --tier standard
hexel compute sandbox exec YOUR_SANDBOX_ID --code "print('Hello from Hexel')"
hexel compute sandbox release YOUR_SANDBOX_ID

4. Deploy an agent

Python
CLI

agent = client.compute.agent.register(
    name="my-agent",
    image="ghcr.io/your-org/agent:v1",
    capabilities=["chat", "streaming"],
)
print(agent["id"])

hexel compute agent register \
  --name my-agent \
  --image ghcr.io/your-org/agent:v1 \
  --capabilities "chat,streaming"

Deploy an instance

CLI
curl

hexel compute instance deploy YOUR_AGENT_ID

curl -X POST https://api.hexelstudio.com/compute/v1/agents/YOUR_AGENT_ID/instances \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"env": {"MODEL": "gpt-4"}}'

The same agent and configuration always produces the same permanent endpoint, even across redeployments.

5. Call your agent

Your agent serves streaming and blocking endpoints at its permanent URL:

https://agent-<name>-<hash>.compute.hexelstudio.com

# Streaming (Server-Sent Events)
curl -N https://agent-my-agent-abc123.compute.hexelstudio.com/stream \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello"}'

# Blocking
curl https://agent-my-agent-abc123.compute.hexelstudio.com/invoke \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello"}'

Next steps

First Deployment

A complete walkthrough of deploying and operating an agent.

Authentication

API keys, OAuth clients, and token handling.

Core Concepts

Understand agents, fleets, tasks, and tools.

Orchestration

Submit multi-step tasks to agent fleets.

​Prerequisites

​1. Install a client

​2. Authenticate

​3. Run code in a sandbox

​4. Deploy an agent

​5. Call your agent

​Next steps

First Deployment

Authentication

Core Concepts

Orchestration

Prerequisites

1. Install a client

2. Authenticate

3. Run code in a sandbox

4. Deploy an agent

5. Call your agent

Next steps