DEV Community: Dennison Bertram

My AI Agent Deploys Code to My Server. Here's What Keeps It in a Box.

Dennison Bertram — Sat, 17 Oct 2026 14:21:16 +0000

My coding agent deploys apps to a server I own. A lot of the time it's shipping code it wrote ten minutes earlier, and I haven't read every line. Usually that's fine. The question I kept coming back to was what happens on the day it isn't fine: a bad dependency, a confused agent, or an app that starts poking at the machine it runs on.

My answer is a sandbox around every app the agent ships. I built it into agentic-hosting, an open-source tool that turns a Linux server into a place AI agents can deploy apps and databases on their own. This post explains in plain terms how that sandbox works, how to set it up on your server, and how to check for yourself that an app is really inside it.

⭐ If this is useful, a star on GitHub helps other people find it.

🤖 Give this to your agent: point it at https://raw.githubusercontent.com/dennisonbertram/agentic-hosting/main/llms.txt and it can sign up and set things up from that one link.

Why a normal container isn't enough

Most apps today ship as containers. A container feels like its own small computer, with its own files and processes. It isn't one. Every container on a machine shares the same Linux kernel with the host and with every other container. The kernel is the core program that controls files, memory, the network, and everything else.

Programs ask the kernel for things through system calls, or syscalls. Opening a file is a syscall. So is sending network data or starting a process. In a normal container, those calls go straight to the host's real kernel. Linux has hundreds of them, and every so often someone finds a bug in one that lets a program break out of its container and reach the host. That's called a container escape.

When I write and deploy the code myself, I can live with that risk. When an agent writes and deploys code all day without me watching, I want another wall.

What gVisor does

gVisor is an open-source project from Google that adds that wall. It gives each container its own kernel, written in Go, that runs as an ordinary program on the host. gVisor calls this kernel the Sentry.

When the app makes a syscall, the Sentry handles it itself instead of passing it to the host kernel. When the app needs files, a separate helper process called the Gofer fetches them. The Sentry itself runs with tight limits on what it can ask the real kernel for. So if the app finds a bug, it's a bug in gVisor's kernel, and getting from there to the host takes a second break-in.

gVisor plugs into Docker as a runtime, which is the piece that actually starts containers. Docker's default runtime is called runc. gVisor's is called runsc. You use the same Docker commands with a different engine underneath.

There are costs, and gVisor's docs are upfront about them. Each syscall takes a longer path, so apps that make a lot of them, like heavy disk or network work, run slower. gVisor also doesn't implement every Linux syscall, so once in a while an app won't run unchanged (see the compatibility notes). For the web apps and APIs I have agents deploy, I'll take that trade.

Setting up gVisor for agentic-hosting

agentic-hosting is a single Go program called ah that runs on your server and takes deploy requests from agents over an HTTP API. The quickstart covers the full install. Here's the gVisor part, on Ubuntu.

Install runsc from gVisor's package repository:

KEYRING=/usr/share/keyrings/gvisor-archive-keyring.gpg
ARCH=$(dpkg --print-architecture)
REPO=https://storage.googleapis.com/gvisor/releases

curl -fsSL https://gvisor.dev/archive.key \
  | sudo gpg --dearmor -o "$KEYRING"
echo "deb [arch=$ARCH signed-by=$KEYRING] $REPO release main" \
  | sudo tee /etc/apt/sources.list.d/gvisor.list
sudo apt-get update && sudo apt-get install -y runsc

Then register it with Docker under the name runsc:

sudo tee /etc/docker/daemon.json <<'JSON'
{
  "runtimes": {
    "runsc": {
      "path": "/usr/bin/runsc"
    }
  },
  "default-address-pools": [{"base":"172.20.0.0/14","size":24}]
}
JSON
sudo systemctl restart docker

The runtimes block is the part that matters. ah asks Docker for a runtime named exactly runsc. The address pool line gives Docker room for a lot of small networks, which ah needs because it creates a private network for each agent and another one for each app.

Check that it worked:

docker info 2>/dev/null | grep runsc
docker run --rm --runtime=runsc hello-world

The first command should show runsc among Docker's runtimes. The second runs a test container inside gVisor.

That's all the gVisor setup there is. ah checks for it every time it starts. In production, if Docker doesn't list runsc, ah exits with this error:

FATAL: gVisor runtime (runsc) not found in Docker daemon. gVisor is required for container isolation in production.

In dev mode (--dev, for trying it on a laptop) it logs a warning instead, but app containers still won't start, because ah always asks for runsc. There's no setting that turns the sandbox off.

What happens when an agent deploys

From the agent's side, the sandbox doesn't show up at all. The agent registers, gets an API key, and asks for a service:

curl -s -X POST "$AH_URL/v1/services" \
  -H "Authorization: Bearer $AH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web",
    "image": "your-dockerhub-user/your-app:1.0",
    "port": 3000
  }'

That request takes a name, an image, a port, and optional environment variables. Nothing else. There's no field for the runtime, extra privileges, or more memory, so the agent can't ask for a looser box even if it wanted one.

Behind that call, ah starts the container with these settings. They're hardcoded in internal/docker/client.go, so you can read them yourself.

Runtime runsc. The app runs on gVisor.
All capabilities dropped (CapDrop: ALL). Linux splits root's powers into pieces called capabilities, like changing file ownership or reconfiguring the network. The app gets none of them.
No new privileges (no-new-privileges). A program inside can't gain more power later, for example through sudo or another setuid program.
Read-only root filesystem (ReadonlyRootfs). The app can't change its own files. It gets small in-memory scratch folders instead: /tmp (64 MB) and /run, /var/run, and /var/tmp (16 MB each). They're all mounted noexec, so nothing written there can run as a program.
256 processes max (PidsLimit). A program that keeps spawning copies of itself hits a wall.
Memory and CPU caps from the agent's quota, 2048 MB and 2 CPUs by default. The memory-plus-swap limit equals the memory limit, so the app gets no swap.
A private network. Each agent's apps sit on their own Docker network, marked internal, with app-to-app traffic turned off. Web traffic comes in through Traefik, the proxy that routes requests, over a separate small network for each app. None of these networks has a route to the internet.

ah also sets the label traefik.enable=false on every app, so an image can't use its own labels to grab another app's traffic. The Postgres and Redis containers it creates for agents run under runsc too.

One practical effect: images that write outside those scratch folders, or that expect to start as root and switch users, will crash here. If an agent's app dies with "Read-only file system" in its logs, that's the reason. The agent can read those logs itself at GET /v1/services/{id}/logs and fix the app.

How to check an app is really sandboxed

I don't like trusting a list of settings in a blog post, including mine. Here's how to check on your own server.

First, ask ah. The detailed health endpoint reports whether gVisor is installed and which version:

curl -s -H "Authorization: Bearer $AH_KEY" \
  "$AH_URL/v1/system/health/detailed"
# {
#   "status": "ok",
#   "docker": {"available": true, ...},
#   "gvisor": {"available": true, "version": "..."},
#   ...
# }

Then look at the container. Get the service's container_id from the API and ask Docker how it was started (this uses jq to pull out the field):

CID=$(curl -s -H "Authorization: Bearer $AH_KEY" \
  "$AH_URL/v1/services/$SERVICE_ID" | jq -r .container_id)

docker inspect --format '{{json .HostConfig}}' "$CID" \
  | jq '{Runtime, ReadonlyRootfs, CapDrop, PidsLimit}'
# {
#   "Runtime": "runsc",
#   "ReadonlyRootfs": true,
#   "CapDrop": [
#     "ALL"
#   ],
#   "PidsLimit": 256
# }

On the host, every gVisor sandbox shows up as its own process:

ps -eo pid,args | grep '[r]unsc-sandbox'

You can also look from inside. If the image has dmesg and touch:

docker exec "$CID" dmesg
# [    0.000000] Starting gVisor...

docker exec "$CID" touch /test
# ... Read-only file system

Under gVisor, dmesg prints gVisor's own made-up boot log instead of the host's kernel log. Some of the lines are jokes, like "Preparing for the zombie uprising...". gVisor's docs point out that this output is easy to fake, so use it as a quick sanity check and trust docker inspect for the real answer.

What the sandbox doesn't cover

gVisor protects the server from the apps. It doesn't solve everything.

Builds are a separate step. When an agent deploys from git, Nixpacks (the tool that turns source code into a container image) builds it with Docker's regular builder, not inside gVisor. The app that comes out of the build runs sandboxed. ah limits where the source can come from: HTTPS URLs on github.com, gitlab.com, bitbucket.org, sr.ht, or codeberg.org.

The API key is the other gap. Anyone holding an agent's key can do anything that agent can, including deploying, deleting, and reading its secrets. They can't reach other agents' apps or register new agents. I give each agent its own key with POST /v1/auth/keys and revoke it when I'm done.

And gVisor is one more wall, not a guarantee. Keep the host patched.

Wrapping up

Every app an agent deploys through agentic-hosting runs inside gVisor, with no extra privileges, a read-only filesystem, capped resources, and a network that only lets web traffic in. The agent can't turn any of that off, and you can check the main settings yourself with one docker inspect command.

Star agentic-hosting on GitHub so more people find it.
Give it to your agent: llms.txt to sign up and set up, or the agent skill for daily use.
Try the quickstart, read the security model, or start at the docs site.
Open an issue if you find a way out of the box. I want to hear about it.

Why One Happy Path Beats a Menu of Options When Your User Is an AI Agent

Dennison Bertram — Thu, 15 Oct 2026 14:17:14 +0000

Give an engineer five ways to deploy an app and they'll pick one. When I gave an AI agent several ways, it tried a few, mixed them together, and left me debugging at midnight.

That's the reason agentic-hosting works the way it does. It's an open-source tool I built that turns a Linux server you own into a place AI coding agents can deploy apps and databases on their own. This post explains its main design rule, one way to do each job, and walks through the API calls an agent makes to go from a git repo to a live URL.

⭐ If this is useful, a star on GitHub helps other people find it.

🤖 Give this to your agent: point it at https://raw.githubusercontent.com/dennisonbertram/agentic-hosting/main/llms.txt (or the skill) and it can sign up and get going from that one link.

Why fewer options

I used to think "only one way to do it" was a sign of an unfinished product. Heroku, Kubernetes, Coolify, and Dokku all give you lots of settings, because people running servers have strong opinions about how to build and route things.

Agents don't have opinions. They make a guess, and if the guess fails they retry, sometimes with a different guess. Every extra option is another branch they can wander down that I never tested.

So agentic-hosting has one build system, one router, and one choice per database type. If there's only one path, the agent can't find a creative one I didn't plan for. Here's what that looks like in practice.

Building: git repo in, running app out

Apps are built with Nixpacks, a tool that looks at your code and figures out how to package it into a container without a Dockerfile. It's the only build option. You can't upload your own Dockerfile.

Deploying from git takes two calls. First the agent creates a service. The API requires an image field, so for git deploys it sends the placeholder "pending":

POST /v1/services
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "name": "my-app",
  "image": "pending",
  "port": 3000
}

Then it starts a build:

POST /v1/services/{serviceID}/builds

{
  "source_type": "git",
  "source_url": "https://github.com/org/repo",
  "source_ref": "main"
}

source_type has to be "git", and source_ref defaults to "main". Only HTTPS URLs from github.com, gitlab.com, bitbucket.org, sr.ht, and codeberg.org are accepted. Anything else gets rejected before the build starts.

While it builds, the agent can watch the logs:

GET /v1/services/{serviceID}/builds/{buildID}/logs?follow=true

Because there's only one build path, the logs always look the same, and when something breaks there's one place to look. In my experience that helps the agent more than which build tool it is.

Routing: you get one URL

Traefik, an open-source proxy, takes incoming web traffic and sends it to the right app. agentic-hosting writes Traefik's config itself. Apps can't set their own routing rules, so a container can't quietly grab another app's traffic.

The URL follows one pattern:

By default: http://{serviceID}.localhost
If you start the server with --base-domain example.com (or set AH_BASE_DOMAIN): https://{dns_label}.example.com, where dns_label comes from the service name

GET /v1/services/{serviceID}
# → includes "url": "http://svc_….localhost"
#    or "https://my-app.example.com"

Custom domains aren't supported yet. That's issue #82.

Databases: Postgres or Redis

The type field takes "postgres" or "redis", and nothing else.

POST /v1/databases

{ "name": "my-db", "type": "postgres" }

It takes about 10 to 30 seconds. Then the agent grabs the connection string, adds it to the app's environment variables, and restarts the app:

GET /v1/databases/{dbID}/connection-string

POST /v1/services/{serviceID}/env
{ "DATABASE_URL": "<connection-string>" }

POST /v1/services/{serviceID}/restart

Environment variables are encrypted on disk and hidden in API responses unless you add ?reveal=true.

The smaller limits

The same thinking shows up in small places. Creating a service accepts name, image, port, and optional env, so the agent can't request more memory or CPU. Images come from Docker Hub or the server's own local registry. And if the agent retries a request with the same Idempotency-Key header within 10 minutes, it won't deploy twice.

None of this limits what you can build. It limits how many ways the agent can get there, which is what I wanted.

Try it

With the server running (see the README, or run ./bin/ah --dev --open-registration --port 8080 on your laptop), the agent's path is:

Register to get an API key.
Create a service with "image": "pending".
Start a build from a git URL.
Watch the build logs, then the app logs at GET /v1/services/{id}/logs?follow=true&tail=100.
Create a Postgres or Redis database, set the env var, restart.
Open the service's url.

If you use Claude Code, the repo also has a skill and /ah-deploy, /ah-db, /ah-logs, and /ah-status commands that do the same steps.

Wrapping up

agentic-hosting gives an AI agent exactly one way to build, route, and add a database, which makes its runs a lot more predictable. You run it on your own server, and the agent does the deploying.

⭐ Star agentic-hosting on GitHub so more people find it.
🤖 Give this to your agent: llms.txt to sign up and set up, or the agent skill for daily use.
📖 Read the docs and try the quickstart.
💬 Open an issue with what you'd want your agent to do next.

And if you hand your agent the keys and something breaks, tell me what it was.

I Gave My Coding Agent a Server of Its Own. Here's How to Do It Safely.

Dennison Bertram — Wed, 14 Oct 2026 13:51:05 +0000

My coding agent writes the app, writes the tests, and catches the bug I missed. Then it stops and hands me a list of deploy commands to run. For a while I just accepted that. Eventually I wanted to know why the last step was still my job.

So I built agentic-hosting. It's open source, and it turns a Linux server you own into a place an AI agent (Claude Code, Cursor, anything that can make HTTP requests) can deploy apps and spin up databases by itself, inside limits you set. This post shows how to install it, hand an agent a key, and watch it ship something.

⭐ If this is useful, a star on GitHub helps other people find it.

🤖 Give this to your agent: point it at https://raw.githubusercontent.com/dennisonbertram/agentic-hosting/main/llms.txt and it can do the setup for you.

Why not just give the agent SSH?

When I first wanted my agent to deploy, I had two options: no access, or root. Neither felt right. Hosting tools are built for people clicking around a dashboard, and an agent with a root shell can do a lot of damage on a bad run.

agentic-hosting is the middle option. Think of it as a Heroku you run on your own machine, except the main user is an agent calling an API. There's a dashboard too, but that's for you to see what the agent did.

The design is deliberately narrow. There's one way to build an app, one way to route traffic to it, and one way to create each kind of database (Postgres or Redis). Each agent gets its own account, called a tenant, with its own API key and rate limits. Every app runs in a sandbox (gVisor, which sits between the container and the server's kernel), so a misbehaving app can't easily touch the host.

The narrowness is the part I care about most. People like choices. Agents mostly use choices as new ways to be wrong.

Under the hood it's one Go program, ah, that runs as a background service on port 8080. Traefik, a standard open-source proxy, takes web traffic on ports 80/443 and passes it to your apps. State lives in SQLite.

Setting it up

You need a Linux server; Ubuntu 22.04 or newer is what I use. The README has the complete script. These are the main steps.

1. Install Docker, gVisor's runsc, Go 1.25, and Nixpacks (the tool that turns source code into a runnable container without a Dockerfile). Then tell Docker about gVisor:

cat > /etc/docker/daemon.json <<'JSON'
{
  "runtimes": { "runsc": { "path": "/usr/bin/runsc" } },
  "default-address-pools": [{"base":"172.20.0.0/14","size":24}]
}
JSON
systemctl restart docker

2. Start the shared pieces: a Docker network, Traefik (copy its docker run command from the README), and a private image registry that only listens locally:

docker network create --driver bridge traefik-public

docker run -d --name paas-registry --restart unless-stopped \
  -p 127.0.0.1:5000:5000 \
  -v /var/lib/ah/registry:/var/lib/registry \
  registry:2

3. Build ah and create its secrets:

git clone https://github.com/dennisonbertram/agentic-hosting /agentic-hosting
cd /agentic-hosting
CGO_ENABLED=1 go build -o bin/ah ./cmd/ah
cp bin/ah /usr/local/bin/ah

mkdir -p /var/lib/ah/builds /var/lib/ah/backups
head -c 32 /dev/urandom | xxd -p -c 64 > /var/lib/ah/master.key
chmod 600 /var/lib/ah/master.key

openssl rand -hex 32   # your bootstrap token

4. Run it. Put the token in /etc/default/ah as AH_BOOTSTRAP_TOKEN=..., install deploy/ah.service, and start it:

systemctl daemon-reload && systemctl enable --now ah
curl -H 'X-Forwarded-Proto: https' http://127.0.0.1:8080/v1/system/health
# → {"status":"ok"}

If you only want to poke at it on your laptop, skip all that and run ./bin/ah --dev --open-registration --port 8080.

Handing an agent the keys

First, create a tenant for the agent. The bootstrap token from step 3 is what lets you do this:

curl -X POST http://localhost:8080/v1/tenants/register \
  -H 'Content-Type: application/json' \
  -H 'X-Bootstrap-Token: <bootstrap-token>' \
  -d '{"name": "my-agent", "email": "me@example.com"}'
# → {"tenant_id": "ten_...", "api_key": "keyid.secret"}

From here the agent sends Authorization: Bearer <api_key> on every request.

Deploying from git is two calls. Create a service, then start a build. The image field is required, so for git deploys you pass "pending":

POST /v1/services
{ "name": "my-app", "image": "pending", "port": 3000 }

POST /v1/services/{serviceID}/builds
{ "source_type": "git", "source_url": "https://github.com/org/repo", "source_ref": "main" }

It builds from GitHub, GitLab, Bitbucket, sr.ht, and Codeberg over HTTPS. The agent can follow the build logs (/builds/{buildID}/logs?follow=true) and the running app's logs (/v1/services/{serviceID}/logs?follow=true&tail=100). This turned out to matter more than I expected. An agent that can read its own crash can usually fix it.

Adding a database:

POST /v1/databases
{ "name": "my-db", "type": "postgres" }   # or "redis"

GET /v1/databases/{dbID}/connection-string

The agent passes that string to the app with POST /v1/services/{serviceID}/env. Environment variables are encrypted on disk and hidden in responses unless you ask for ?reveal=true.

The app shows up at http://{serviceID}.localhost, or at https://{dns_label}.example.com if you start ah with --base-domain example.com.

Skipping the curl entirely

If you use Claude Code, the repo includes a skill and a few commands so you can just ask:

mkdir -p ~/.claude/skills/agentic-hosting
cp .claude/skills/agentic-hosting/SKILL.md ~/.claude/skills/agentic-hosting/SKILL.md
cp .claude/commands/ah-*.md ~/.claude/commands/

Then in Claude Code:

/ah-deploy https://github.com/org/my-app web 3000
/ah-db web postgres
/ah-logs web
/ah-status

There's also /ah-register to create a tenant and /ah-snapshot to snapshot a running service. Not on Claude? The same flows are bash scripts in scripts/.

The first time I watched the agent deploy, read the logs, fix a crash, and redeploy without me, I found myself checking in on it the way you'd check on a new hire.

What keeps it from going wrong

I don't trust the agent to be careful. I trust the limits around it:

Every 30 seconds, ah checks that what it thinks is running matches what Docker is actually running, and fixes the difference.
If an app crashes 5 times in 10 minutes, it stops restarting it. Turning it back on takes an explicit API call.
At 80% disk it warns. At 90% it refuses new deploys, builds, and databases.
Each tenant is rate-limited to 100 requests a second, with bursts up to 200.
Requests can carry an idempotency key, so if the agent retries within 10 minutes, nothing deploys twice.
ah backup snapshots the SQLite databases and keeps the last 10.

It's still early. There's no billing yet (usage is tracked but only queryable), no Prometheus metrics, and it runs on a single server. Read the security section of the README before you give anyone a key.

Wrapping up

agentic-hosting lets your coding agent deploy apps and databases on a server you own, with sandboxing and limits so a bad run stays small. You install it once, give each agent its own tenant, and let it work. The quickest way to try it is --dev mode on your laptop.

⭐ Star agentic-hosting on GitHub so more people find it.
🤖 Give this to your agent: send it to llms.txt to set up and sign up, or install the agent skill so it knows the day-to-day commands.
📖 Read the docs for the full API.
💬 Open an issue and tell me what you want your agent to do next.

If you hand your agent a server, I'd like to hear what it does with it.

Building an ICO on Canton Network

Dennison Bertram — Wed, 12 Nov 2025 21:06:22 +0000

A hands-on guide to creating privacy-preserving token sales on Canton Network

Ever wanted to build a token sale where only the buyer, seller, and maybe a regulator can see the details? That's exactly what we're going to create today. We'll build a complete ICO (Initial Coin Offering) smart contract that sells one token for another, with privacy built-in and atomic operations that can't fail halfway through.

What's an ICO Anyway?

ICO's are back! From Monad to MegaETH or projects launching their token on Tally.xyz, capital formation as product market fit for crypto is the meta.

Before we dive into code, let's make sure we're on the same page. An ICO (Initial Coin Offering) is when a project sells their tokens to raise funds. Traditionally this happens on public blockchains where everyone can see:

Who bought what
How much they paid
All the transaction details

But what if you want to keep those details private? That's where Canton Network comes in.

Why Canton Network?

Canton Network is different. It gives you:

🔒 Privacy by Default
Only the parties directly involved in a transaction can see the details. No more public order books!

⚡ Atomic Operations
Either everything happens (buyer pays, seller delivers) or nothing happens. No failed transactions leaving things in a weird state.

🤝 Multi-Party Authorization
Smart contracts can require multiple parties to agree before anything happens. Perfect for regulated token sales.

🏗️ Enterprise Ready
Built for serious applications with proper tooling, monitoring, and compliance features.

What We're Building

We'll create a complete ICO system with three parts:

Token Contract - A simple but secure token that can be issued and transferred
ICO Contract - The main sale logic with atomic token-for-token swaps
Test Suite - Scripts to verify everything works correctly

The flow will be:

Buyer pays with USDC → ICO contract validates → MYCOIN tokens created → All in one atomic transaction

Quick Setup

Let's get your environment ready. You'll need:

Daml SDK (version 3.3.0-snapshot...)
Java 21 (for the build tools)
Docker (for running the local network)
tmux (for managing long-running processes)

The easiest way is to clone the Canton quickstart repo and run their setup:

git clone https://github.com/digital-asset/cn-quickstart.git
cd cn-quickstart/quickstart
make setup

This gives you a complete development environment with Canton nodes, wallets, and monitoring tools.

Want to get started with AI? Use this llms.txt to get started fast.

Your First ICO Contract

Let's start with a simple token contract. Create a file called Token.daml:

module Token where

import DA.Assert

-- A simple token that can be issued and transferred
template Token
  with
    issuer : Party     -- Who created this token
    owner : Party      -- Who currently owns it
    symbol : Text      -- Like "USD" or "MYCOIN"
    amount : Decimal   -- How much
  where
    ensure amount > 0.0
    signatory issuer, owner  -- Both must agree to create it

    -- Transfer ownership to someone else
    choice Transfer : ContractId Token
      with
        newOwner : Party
      controller owner, newOwner  -- Both current and new owner must agree
      do
        create this with owner = newOwner

-- The authority that can create new tokens
template TokenIssuer
  with
    issuer : Party
    symbol : Text
    totalSupply : Decimal
  where
    signatory issuer

    -- Create new tokens for someone (doesn't consume this contract)
    nonconsuming choice IssueTokens : ContractId Token
      with
        recipient : Party
        amount : Decimal
      controller issuer, recipient  -- Both issuer and recipient must agree
      do
        assert (amount > 0.0)
        create Token with
          issuer = issuer
          owner = recipient
          symbol = symbol
          amount = amount

Now let's create the ICO contract in Ico.daml:

module Ico where

import DA.Assert
import DA.Time
import Token

-- An active ICO where people can buy tokens
template IcoOffering
  with
    issuer : Party                    -- The company running the ICO
    saleTokenIssuer : Party           -- Who creates the tokens being sold
    saleTokenSymbol : Text            -- What token is being sold
    paymentTokenIssuer : Party        -- Who creates the payment tokens
    paymentTokenSymbol : Text         -- What token buyers pay with
    exchangeRate : Decimal            -- How many sale tokens per payment token
    totalSaleTokens : Decimal         -- Total available for sale
    tokensSold : Decimal              -- How many sold so far
    totalRaised : Decimal             -- Total payment collected
    startTime : Time                  -- When ICO starts
    endTime : Time                    -- When ICO ends
    minPurchase : Decimal             -- Minimum purchase amount
    maxPurchase : Decimal             -- Maximum purchase (0 = no limit)
  where
    ensure totalSaleTokens > 0.0 && exchangeRate > 0.0
    signatory issuer

    -- Buy tokens! This is the magic atomic swap
    choice Purchase : (ContractId Token.Token, ContractId IcoOffering)
      with
        buyer : Party
        paymentTokenCid : ContractId Token.Token  -- Buyer's payment token
        paymentAmount : Decimal                   -- How much they're paying
      controller buyer, issuer, saleTokenIssuer   -- All three parties must agree!
      do
        -- Check if ICO is active
        now <- getTime
        assert (now >= startTime)
        assert (now < endTime)

        -- Validate purchase amount
        assert (paymentAmount >= minPurchase)
        assert (maxPurchase == 0.0 || paymentAmount <= maxPurchase)

        -- Calculate how many tokens they get
        let saleTokenAmount = paymentAmount * exchangeRate

        -- Make sure we have enough tokens left
        let remainingTokens = totalSaleTokens - tokensSold
        assert (saleTokenAmount <= remainingTokens)

        -- Verify they own the payment token
        paymentToken <- fetch paymentTokenCid
        assert (paymentToken.issuer == paymentTokenIssuer)
        assert (paymentToken.symbol == paymentTokenSymbol)
        assert (paymentToken.owner == buyer)
        assert (paymentToken.amount >= paymentAmount)

        -- Handle payment (split if needed, then transfer)
        if paymentToken.amount == paymentAmount
          then do
            -- Exact amount: transfer the whole token
            _ <- exercise paymentTokenCid Token.Transfer with
                newOwner = issuer
            return ()
          else do
            -- Partial payment: split and transfer just the payment amount
            (paymentPortionCid, _changeCid) <- exercise paymentTokenCid Token.Split with
                splitAmount = paymentAmount
            _ <- exercise paymentPortionCid Token.Transfer with
                newOwner = issuer
            return ()

        -- Create the sale tokens for the buyer
        saleTokenCid <- create Token.Token with
          issuer = saleTokenIssuer
          owner = buyer
          symbol = saleTokenSymbol
          amount = saleTokenAmount

        -- Update the ICO with new totals
        updatedIcoCid <- create this with
          tokensSold = tokensSold + saleTokenAmount
          totalRaised = totalRaised + paymentAmount

        return (saleTokenCid, updatedIcoCid)

    -- Close the ICO when it's done
    choice Close : ContractId IcoCompleted
      controller issuer
      do
        now <- getTime
        assert (now >= endTime || tokensSold >= totalSaleTokens)
        create IcoCompleted with
          issuer = issuer
          saleTokenIssuer = saleTokenIssuer
          saleTokenSymbol = saleTokenSymbol
          paymentTokenIssuer = paymentTokenIssuer
          paymentTokenSymbol = paymentTokenSymbol
          totalSaleTokens = totalSaleTokens
          tokensSold = tokensSold
          totalRaised = totalRaised
          finalExchangeRate = exchangeRate

-- Record of a completed ICO
template IcoCompleted
  with
    issuer : Party
    saleTokenIssuer : Party
    saleTokenSymbol : Text
    paymentTokenIssuer : Party
    paymentTokenSymbol : Text
    totalSaleTokens : Decimal
    tokensSold : Decimal
    totalRaised : Decimal
    finalExchangeRate : Decimal
  where
    signatory issuer

    -- Get final statistics
    nonconsuming choice GetStats : (Decimal, Decimal, Decimal)
      controller issuer
      do return (tokensSold, totalRaised, finalExchangeRate)

-- Helper to create ICOs
template IcoFactory
  with
    issuer : Party
  where
    signatory issuer

    choice CreateIco : ContractId IcoOffering
      with
        saleTokenIssuer : Party
        saleTokenSymbol : Text
        paymentTokenIssuer : Party
        paymentTokenSymbol : Text
        exchangeRate : Decimal
        totalSaleTokens : Decimal
        startTime : Time
        endTime : Time
        minPurchase : Decimal
        maxPurchase : Decimal
      controller issuer
      do
        assert (totalSaleTokens > 0.0)
        assert (exchangeRate > 0.0)
        assert (endTime > startTime)
        assert (minPurchase > 0.0)

        create IcoOffering with
          issuer = issuer
          saleTokenIssuer = saleTokenIssuer
          saleTokenSymbol = saleTokenSymbol
          paymentTokenIssuer = paymentTokenIssuer
          paymentTokenSymbol = paymentTokenSymbol
          exchangeRate = exchangeRate
          totalSaleTokens = totalSaleTokens
          tokensSold = 0.0
          totalRaised = 0.0
          startTime = startTime
          endTime = endTime
          minPurchase = minPurchase
          maxPurchase = maxPurchase

Testing It Out

Let's create a test script to verify our ICO works. Create IcoTest.daml:

module IcoTest where

import DA.Assert
import DA.Time
import Daml.Script
import Ico
import Token

test_ico_lifecycle = script do
  -- Create all the parties
  icoIssuer <- allocateParty "Company"
  saleTokenIssuer <- allocateParty "Company"
  paymentTokenIssuer <- allocateParty "USDCIssuer"
  buyer1 <- allocateParty "Alice"
  buyer2 <- allocateParty "Bob"

  -- Create token issuers
  saleIssuerCid <- submit saleTokenIssuer do
    createCmd TokenIssuer with
      issuer = saleTokenIssuer
      symbol = "MYCOIN"
      totalSupply = 1000000.0

  paymentIssuerCid <- submit paymentTokenIssuer do
    createCmd TokenIssuer with
      issuer = paymentTokenIssuer
      symbol = "USDC"
      totalSupply = 1000000.0

  -- Give buyers some USDC to spend
  buyer1PaymentCid <- submitMulti [paymentTokenIssuer, buyer1] [] do
    exerciseCmd paymentIssuerCid IssueTokens with
      recipient = buyer1
      amount = 1000.0

  buyer2PaymentCid <- submitMulti [paymentTokenIssuer, buyer2] [] do
    exerciseCmd paymentIssuerCid IssueTokens with
      recipient = buyer2
      amount = 500.0

  -- Set up the ICO
  now <- getTime
  factoryCid <- submit icoIssuer do
    createCmd IcoFactory with issuer = icoIssuer

  icoCid <- submit icoIssuer do
    exerciseCmd factoryCid CreateIco with
      saleTokenIssuer = saleTokenIssuer
      saleTokenSymbol = "MYCOIN"
      paymentTokenIssuer = paymentTokenIssuer
      paymentTokenSymbol = "USDC"
      exchangeRate = 100.0  -- 1 USDC = 100 MYCOIN
      totalSaleTokens = 50000.0
      startTime = now
      endTime = addRelTime now (days 1)
      minPurchase = 10.0
      maxPurchase = 0.0

  -- Alice buys 100 USDC worth (gets 10,000 MYCOIN)
  (aliceTokensCid, icoCid1) <- submitMulti [buyer1, icoIssuer, saleTokenIssuer] [] do
    exerciseCmd icoCid Purchase with
      buyer = buyer1
      paymentTokenCid = buyer1PaymentCid
      paymentAmount = 100.0

  -- Verify Alice got her tokens
  Some aliceTokens <- queryContractId buyer1 aliceTokensCid
  assert (aliceTokens.amount == 10000.0)
  assert (aliceTokens.symbol == "MYCOIN")

  -- Bob buys 50 USDC worth (gets 5,000 MYCOIN)
  (bobTokensCid, icoCid2) <- submitMulti [buyer2, icoIssuer, saleTokenIssuer] [] do
    exerciseCmd icoCid1 Purchase with
      buyer = buyer2
      paymentTokenCid = buyer2PaymentCid
      paymentAmount = 50.0

  -- Verify Bob got his tokens
  Some bobTokens <- queryContractId buyer2 bobTokensCid
  assert (bobTokens.amount == 5000.0)

  -- Check ICO totals
  Some finalIco <- queryContractId icoIssuer icoCid2
  assert (finalIco.tokensSold == 15000.0)  -- 10k + 5k
  assert (finalIco.totalRaised == 150.0)   -- 100 + 50

  return ()

Testing It Out

Run the tests to make sure everything works:

# In the cn-quickstart/quickstart directory
cd daml/ico-token
daml test

You should see something like:

Test suite passed with 8 transactions and 9 active contracts

Deploying to LocalNet

Time to see your ICO running on a real Canton network! The build scripts handle all the complexity:

# Build the contracts
cd examples/ico-token
./scripts/build.sh

# Deploy to local network
./scripts/deploy.sh

This will:

Compile your Daml contracts into a DAR file
Start Canton participant nodes
Launch web interfaces for exploration
Deploy your contracts to the ledger

Once running, you can access:

Scan UI: http://scan.localhost:4000 (explore contracts)
Wallet UI: http://wallet.localhost:2000 (manage tokens)
App Provider: http://app-provider.localhost:3000 (frontend)

Making It Real

Your ICO is now live on LocalNet! Here's how to interact with it:

Create parties through the wallet interfaces
Issue tokens using the TokenIssuer contracts
Set up an ICO using the IcoFactory
Make purchases through the Purchase choice
Watch the magic happen atomically

The best part? Only the buyer, seller, and sale token issuer can see the transaction details. Everyone else just sees that a transaction happened.

What's Next?

🎉 Congratulations! You just built a privacy-preserving ICO on Canton Network.

Want to take it further? Here are some ideas:

Add Features

Tiered pricing: Different rates for different purchase amounts
Time bonuses: Better rates for early buyers
Vesting: Lock purchased tokens for a period
KYC integration: Verify buyer identities

Go Production

Multi-party deployments: Run across different Canton domains
Compliance: Add regulator observers
Monitoring: Set up proper observability
Scaling: Handle thousands of concurrent buyers

Learn More

Daml patterns: Explore more Canton-specific smart contract patterns
Privacy models: Deep dive into sub-transaction privacy
Integration: Connect with existing DeFi protocols

The Canton ecosystem is growing fast. Your ICO contract is a great foundation for building the next generation of token sales!

About the Author

Dennison Bertram is the co-founder and CEO of Tally.xyz, the infrastructure layer for tokens—from ICO and airdrop to governance, staking, and value accrual. Tally delivers the complete framework for operating tokens at scale, powering the largest teams in the ecosystem with billions under management.