Getting started

Quickstart

Go from an empty bucket to an agent that answers questions over your files — with citations back to the bytes on Walrus.

Open app.kraterion.com and sign in with Google. Behind the scenes this is zkLogin — you get a Sui account derived from your login, with no seed phrase to manage. Your buckets and files will be owned by that account.

Create a bucket

Create your first bucket from the dashboard. Buckets are created in the app rather than over the S3 API on purpose: a bucket is an on-chain object whose owner is set to you, so creating one needs your signature. Calling CreateBucket over S3 returns 501 NotImplemented.

Generate an API key

In the dashboard, create an S3 key. You'll get an access key id (starting with AKIA) and a secret. The secret is shown once — copy it now. Kraterion uses two kinds of credentials: S3 keys for the storage API, and bearer tokens for everything else. See API keys.

Upload a file

Point any S3 client at s3.kraterion.com. We'll use boto3. The region can be anything — the gateway reads the service but ignores the region.

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.kraterion.com",
    aws_access_key_id="AKIA...",
    aws_secret_access_key="...",
    region_name="us-east-1",
)

# Upload a file
s3.upload_file("handbook.md", "my-bucket", "handbook.md")

# List what's in the bucket (use V2 — V1 is not supported)
for obj in s3.list_objects_v2(Bucket="my-bucket").get("Contents", []):
    print(obj["Key"], obj["Size"])

The file is encrypted at the gateway before it's stored, so the bytes on Walrus are ciphertext. Reads are decrypted transparently while your key is authorized.

Enable knowledge

Turn on knowledge for the bucket to make it searchable. Kraterion chunks and embeds every object so agents can retrieve passages with citations. Enabling needs an OpenAI key configured on the project (Kraterion uses your key to embed). Toggle it in the dashboard, or over the API with a bearer token:

curl -X POST https://api.kraterion.com/v1/buckets/<bucket_id>/knowledge \
  -H "Authorization: Bearer kr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Create an agent

Create an agent and attach the bucket. An agent is a saved configuration — a system prompt, a model, the buckets it can see, and the tools it can call. Use the dashboard, or the API:

curl -X POST https://api.kraterion.com/v1/projects/<project_id>/agents \
  -H "Authorization: Bearer kr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "handbook-bot",
    "system_prompt": "Answer questions using the company handbook.",
    "model": "gpt-4o-mini",
    "bucket_ids": ["<bucket_id>"],
    "tools": ["kraterion_search"]
  }'

Invoke the agent

The agent speaks the OpenAI Chat Completions protocol, so the official OpenAI SDK works unchanged — just point its base URL at the agent and use your bearer token as the API key.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.kraterion.com/v1/agents/<agent_id>",
    api_key="kr_live_...",
)

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "What's our refund window?"}],
)

print(resp.choices[0].message.content)
# Citations and retrieval info arrive in the response's "kraterion" field.

That's the whole loop. From here, give the agent more tools, wire up memory, or embed it on your site.