Skip to main content
Lucid provides three paths for developers who want to build custom agents. All paths result in the same outcome: a verified agent with a passport identity, an auto-created wallet, and automatic receipt generation.

​
Path A: Bring Your Own Image

The fastest path if you already have a working agent packaged as a Docker image. 
lucid launch \
  --image ghcr.io/myorg/my-agent:latest \
  --target railway \
  --owner 0x...
Lucid injects environment variables into your container so your agent can connect to the network: 
// Your agent code
import { RaijinLabsLucidAi } from "raijin-labs-lucid-ai";

const lucid = new RaijinLabsLucidAi({
  serverURL: process.env.LUCID_API_URL || "https://api.lucid.foundation",
  security: { bearerAuth: process.env.LUCID_API_KEY },
});

const result = await lucid.run.chatCompletions({
  body: {
    model: "openai/gpt-4o",
    messages: [{ role: "user", content: "Summarize this document" }],
  },
});
The generated SDK client handles:
  • Inference via any OpenAI-compatible endpoint
  • Automatic receipt creation on every call (fire-and-forget)
  • Failed receipts queued in-memory with exponential backoff (max 5 attempts)
  • Environment-based configuration (zero manual setup)

​
Path C: Build from Source

If you have source code but no Docker image: 
# Set up a container registry for remote targets
lucid registry set ghcr.io/myorg --username x --token y

# Launch from source directory
lucid launch --path ./my-agent --target railway --owner 0x...
Lucid will:
  1. Detect your Dockerfile (or generate one)
  2. Build the image locally
  3. Push to your configured registry
  4. Deploy to the target provider
For Docker-only targets, the registry push is skipped.

​
Agent Structure

A minimal Lucid-compatible agent needs: 
// server.ts
import express from "express";
import { RaijinLabsLucidAi } from "raijin-labs-lucid-ai";

const app = express();
const lucid = new RaijinLabsLucidAi({
  serverURL: process.env.LUCID_API_URL || "https://api.lucid.foundation",
  security: { bearerAuth: process.env.LUCID_API_KEY },
});

app.post('/run', async (req, res) => {
  const result = await lucid.run.chatCompletions({
    body: {
      model: process.env.LUCID_MODEL || "openai/gpt-4o",
      messages: [{ role: "user", content: req.body.prompt }],
    },
  });
  res.json(result);
});

app.listen(3100);

FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
EXPOSE 3100
CMD ["node", "server.js"]

​
Registering Skills

If your agent has capabilities other agents should discover, register them as tool passports: 
# Register all skills from your agent
lucid agent skills register my-agent

# Preview what would be registered
lucid agent skills register my-agent --dry-run
Skills are extracted from SKILL.md frontmatter in the Docker image, or from the catalog manifest.

​
Connecting Channels

Add messaging channels during launch or afterward: 
# At launch with env vars
lucid launch --image my-agent:latest --target docker \
  --env TELEGRAM_BOT_TOKEN=123:ABC \
  --env DISCORD_BOT_TOKEN=xyz

# Or via config file
lucid launch --image my-agent:latest --target docker --config ./my.env

​
Choosing a Deployment Target

TargetBest For
dockerLocal development and testing
railwayQuick cloud deployment with auto-domain
akashDecentralized, cost-effective compute
phalaPrivacy-sensitive agents (TEE)
ionetGPU-intensive workloads
nosanaPersistent GPU services

​
Memory Integration

Enable agent memory for persistent context: 
lucid launch --image my-agent:latest --target docker \
  --env MEMORY_ENABLED=true \
  --env MEMORY_STORE=sqlite
Your agent can then use the memory API for 6 memory types: episodic, semantic, procedural, entity, trust-weighted, and temporal.