62 KiB
62 KiB
Plan 03: Sprites.dev Support
First remote sandbox executor using the Sprites.dev service. Depends on: Plan 01 (Secrets Infrastructure), Plan 02 (Executor Profiles Infrastructure).
Table of Contents
- Overview
- Architecture
- Sprites.dev Concepts
- Backend Implementation
- Environment Preparation
- agentctl Deployment & Connection
- Session Resume & Recovery
- Settings Page
- Debug & Test Harness
- API Endpoints
- Frontend Implementation
- Error Handling & Edge Cases
Overview
Sprites.dev is a paid service that provides ephemeral sandbox environments (sprites). Users provide their API key, and Kandev creates sprites on their behalf to run agents in isolated environments.
Goals
- Implement
SpritesExecutorbackend (implementsExecutorBackendinterface from Plan 02) - Deploy and run agentctl inside sprites via the sprites-go SDK
- Establish port-forwarded connections between kandev backend and agentctl in sprite
- Settings page for Sprites account setup (API key, network policies, running sprites)
- Environment preparation: install agent CLI, node.js, copy auth files
- Session resume with health checking
- Comprehensive debug logging and test harness
Prerequisites
- Plan 01 (Secrets) must be implemented — API key stored in secrets store
- Plan 02 (Executor Profiles) must be implemented — executor/profile model in place
Key SDK
github.com/superfly/sprites-go
The SDK provides:
sprites.New(token)— create client with API tokenclient.Sprite(name)— get sprite handlesprite.Command(cmd, args...)— run commands (mirrorsexec.Cmd)sprite.CommandContext(ctx, cmd, args...)— with contextsprite.ProxyPort(ctx, localPort, remotePort)— TCP port forwardingsprite.ProxyPorts(ctx, []PortMapping{...})— multiple port forwardingcmd.StdinPipe(),cmd.StdoutPipe()— pipe accesscmd.SetTTY(true)— TTY mode
Sprites API:
POST /v1/sprites— create spriteDELETE /v1/sprites/{name}— destroy spriteGET /v1/sprites— list spritesGET /v1/sprites/{name}— get sprite statusWSS /v1/sprites/{name}/exec— execute commandsPOST /v1/sprites/{name}/services— create background serviceGET/POST /v1/sprites/{name}/network— network policiesWSS proxy— TCP port tunneling
Architecture
High-Level Flow
┌───────────────────────────────────────────────────────────────────────────┐
│ Kandev Backend │
│ │
│ ┌─────────────┐ ┌─────────────────┐ ┌──────────────────────────┐ │
│ │ Orchestrator │───>│ Lifecycle Mgr │───>│ SpritesExecutor │ │
│ │ │ │ │ │ (ExecutorBackend impl) │ │
│ │ task.start │ │ LaunchAgent() │ │ │ │
│ │ executor= │ │ profile= │ │ 1. Create sprite │ │
│ │ sprites │ │ sprites/def │ │ 2. Prepare environment │ │
│ │ │ │ │ │ 3. Deploy agentctl │ │
│ │ │ │ │ │ 4. Start agentctl │ │
│ │ │ │ │ │ 5. Port forward │ │
│ │ │ │ │ │ 6. Return client │ │
│ └─────────────┘ └─────────────────┘ └──────────┬───────────────┘ │
│ │ │
│ ┌──────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Port Forwarding (sprites-go SDK) │ │
│ │ │ │
│ │ localhost:$LOCAL_PORT ←──WSS tunnel──→ sprite:$AGENTCTL_PORT │ │
│ │ │ │
│ │ agentctl.Client connects to localhost:$LOCAL_PORT │ │
│ │ which tunnels to agentctl running inside the sprite │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────┘
│
│ WSS tunnel (sprites-go SDK manages)
▼
┌───────────────────────────────────────────────────────────────────────────┐
│ Sprites.dev Cloud │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Sprite: kandev-sess-abc123 │ │
│ │ │ │
│ │ ┌───────────────────────────────────────────────────────────────┐ │ │
│ │ │ agentctl process (port 8765) │ │ │
│ │ │ │ │ │
│ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ Agent subprocess (claude-code, codex, etc.) │ │ │ │
│ │ │ │ stdin/stdout ←→ ACP protocol ←→ agentctl │ │ │ │
│ │ │ └─────────────────────────────────────────────────────────┘ │ │ │
│ │ │ │ │ │
│ │ │ /workspace/ ← git clone of repo │ │ │
│ │ │ ~/.config/ ← copied agent configs │ │ │
│ │ │ ~/.gitconfig ← copied git config │ │ │
│ │ │ Auth tokens for gh, git, etc. │ │ │
│ │ └───────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────┘
Detailed Sequence Diagram
Orchestrator LifecycleMgr SpritesExecutor SpritesPreparer Sprites API Sprite
│ │ │ │ │ │
│ LaunchAgent() │ │ │ │ │
│───────────────>│ │ │ │ │
│ │ resolve profile│ │ │ │
│ │ (api_token from│ │ │ │
│ │ secrets store)│ │ │ │
│ │ │ │ │ │
│ │ CreateInstance()│ │ │ │
│ │───────────────>│ │ │ │
│ │ │ POST /v1/sprites │ │
│ │ │───────────────────────────────>│ │
│ │ │ │ sprite created │
│ │ │<───────────────────────────────│ │
│ │ │ │ │ │
│ │ Prepare() │ │ │ │
│ │───────────────────────────────>│ │ │
│ │ │ │ install node │ │
│ │ │ │───────────────────────────────>│
│ │ │ │ install agent │ │
│ │ │ │───────────────────────────────>│
│ │ │ │ copy configs │ │
│ │ │ │───────────────────────────────>│
│ │ │ │ clone repo │ │
│ │ │ │───────────────────────────────>│
│ │ │ │<──────────────────────────────│
│ │<──────────────────────────────│ │ │
│ │ │ │ │ │
│ │ │ upload agentctl│ │ │
│ │ │ binary │ │ │
│ │ │───────────────────────────────────────────────>│
│ │ │ │ │ │
│ │ │ start agentctl │ │ │
│ │ │ as service │ │ │
│ │ │───────────────────────────────>│ │
│ │ │ │ POST /services│ │
│ │ │<───────────────────────────────│ │
│ │ │ │ │ │
│ │ │ ProxyPort() │ │ │
│ │ │ local:random ←→ sprite:8765 │ │
│ │ │───────────────────────────────>│ │
│ │ │ ← WSS tunnel established ──── │ │
│ │ │ │ │ │
│ │ │ return ExecutorInstance │ │
│ │ │ (client=localhost:random) │ │
│ │<───────────────│ │ │ │
│ │ │ │ │ │
│ │ ConfigureAgent()│ │ │ │
│ │ via agentctl │ │ │ │
│ │ client (tunnel)│ │ │ │
│ │═══════════════════════════════════════════════════════════════>│
│ │ │ │ │ │
│ │ Start() agent │ │ │ │
│ │═══════════════════════════════════════════════════════════════>│
│ │ │ │ │ │
│<═══════════════│ stream updates │ │ │ │
│ via WS │ via tunnel │ │ │ │
Sprites.dev Concepts
Sprite Lifecycle
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Creating │────>│ Ready │────>│ Running │────>│ Stopped │
│ │ │ │ │ (services│ │ │
│ │ │ │ │ active) │ │ (destroy)│
└──────────┘ └──────────┘ └──────────┘ └──────────┘
│ │
│ ┌─────────┘
▼ ▼
┌──────────────┐
│ Checkpointed │ (optional, save state)
└──────────────┘
Naming Convention
Sprites are named: kandev-{session_id_short} (e.g., kandev-abc12345)
This allows:
- Easy identification of Kandev-managed sprites
- Recovery by listing sprites with
kandev-prefix - Cleanup of orphaned sprites
Network Policies
Sprites can have DNS-based outbound network policies. Users configure these per-profile:
{
"network_policies": [
"*.npm.org",
"*.github.com",
"*.githubusercontent.com",
"registry.npmjs.org",
"pypi.org",
"*.anthropic.com"
]
}
These are applied via the Sprites API POST /v1/sprites/{name}/network.
Backend Implementation
Package Structure
apps/backend/internal/agent/lifecycle/
├── executor_sprites.go # SpritesExecutor (ExecutorBackend impl)
├── env_preparer_sprites.go # SpritesEnvironmentPreparer
└── sprites_client.go # Sprites SDK wrapper/helpers
apps/backend/internal/sprites/
├── settings.go # Sprites settings service
└── handlers.go # Sprites-specific API handlers (list sprites, network policies)
SpritesExecutor: lifecycle/executor_sprites.go
package lifecycle
import (
"context"
"fmt"
"net"
sprites "github.com/superfly/sprites-go"
"go.uber.org/zap"
"github.com/kandev/kandev/internal/agent/executor"
agentctl "github.com/kandev/kandev/internal/agentctl/client"
"github.com/kandev/kandev/internal/agentctl/server/process"
"github.com/kandev/kandev/internal/common/logger"
)
const (
spritesAgentctlPort = 8765
spritesNamePrefix = "kandev-"
)
// SpritesExecutor implements ExecutorBackend for Sprites.dev sandbox environments.
type SpritesExecutor struct {
secretsProvider SecretsProvider // to fetch API token
logger *logger.Logger
// Active proxy sessions keyed by instance ID
proxies map[string]*SpritesProxy
}
// SpritesProxy holds the tunnel and sprite handle for an active instance.
type SpritesProxy struct {
client *sprites.Client
sprite *sprites.Sprite
spriteName string
localPort int
cancelFn context.CancelFunc
}
func NewSpritesExecutor(secretsProvider SecretsProvider, log *logger.Logger) *SpritesExecutor {
return &SpritesExecutor{
secretsProvider: secretsProvider,
logger: log.WithFields(zap.String("executor", "sprites")),
proxies: make(map[string]*SpritesProxy),
}
}
func (e *SpritesExecutor) Name() executor.Name {
return executor.NameSprites
}
func (e *SpritesExecutor) IsRemote() bool {
return true
}
func (e *SpritesExecutor) HealthCheck(ctx context.Context) error {
// Try to get API token from secrets
token, err := e.secretsProvider.GetSecret(ctx, "SPRITES_API_TOKEN")
if err != nil {
return fmt.Errorf("sprites API token not configured: %w", err)
}
// Try listing sprites to verify token works
client := sprites.New(token)
sprite := client.Sprite("kandev-healthcheck")
// Simple command to verify API connectivity
cmd := sprite.CommandContext(ctx, "echo", "health")
// If the sprite doesn't exist, the API will return an error
// which is fine — we just want to verify the token is valid
_ = cmd // We don't actually run this — just verify client creation works
return nil
}
func (e *SpritesExecutor) CreateInstance(
ctx context.Context,
req *ExecutorCreateRequest,
) (*ExecutorInstance, error) {
// 1. Get API token from profile config → secrets store
tokenSecretID, _ := req.ProfileConfig["api_token_secret_id"].(string)
token, err := e.secretsProvider.GetSecret(ctx, tokenSecretID)
if err != nil {
return nil, fmt.Errorf("sprites API token: %w", err)
}
// 2. Create sprites client
client := sprites.New(token)
// 3. Create sprite with unique name
spriteName := fmt.Sprintf("%s%s", spritesNamePrefix, req.SessionID[:8])
sprite := client.Sprite(spriteName)
e.logger.Info("creating sprite",
zap.String("name", spriteName),
zap.String("session_id", req.SessionID))
// 4. Verify sprite is accessible by running a simple command
cmd := sprite.CommandContext(ctx, "echo", "kandev-ready")
output, err := cmd.Output()
if err != nil {
return nil, fmt.Errorf("sprite creation/access failed: %w", err)
}
e.logger.Debug("sprite ready", zap.String("output", string(output)))
// 5. Set up port forwarding
localPort, err := getFreePort()
if err != nil {
return nil, fmt.Errorf("get free port: %w", err)
}
proxyCtx, proxyCancel := context.WithCancel(context.Background())
go func() {
if proxyErr := sprite.ProxyPort(proxyCtx, localPort, spritesAgentctlPort); proxyErr != nil {
e.logger.Error("sprite port proxy failed",
zap.String("sprite", spriteName),
zap.Error(proxyErr))
}
}()
// 6. Store proxy info for cleanup
e.proxies[req.InstanceID] = &SpritesProxy{
client: &client, // Note: need to check SDK type
sprite: &sprite,
spriteName: spriteName,
localPort: localPort,
cancelFn: proxyCancel,
}
// 7. Create agentctl client pointing to the local end of the tunnel
agentctlClient := agentctl.NewClient("127.0.0.1", localPort, e.logger)
e.logger.Info("sprite instance created",
zap.String("sprite", spriteName),
zap.String("instance_id", req.InstanceID),
zap.Int("local_port", localPort))
return &ExecutorInstance{
InstanceID: req.InstanceID,
TaskID: req.TaskID,
SessionID: req.SessionID,
BackendName: string(e.Name()),
Client: agentctlClient,
RemoteID: spriteName,
Metadata: map[string]interface{}{
"sprite_name": spriteName,
"local_port": localPort,
},
}, nil
}
func (e *SpritesExecutor) StopInstance(
ctx context.Context,
instance *ExecutorInstance,
force bool,
) error {
proxy, ok := e.proxies[instance.InstanceID]
if !ok {
return nil
}
// Cancel port forwarding
proxy.cancelFn()
// Destroy sprite
spriteName := instance.RemoteID
if spriteName != "" {
sprite := proxy.client.Sprite(spriteName)
// Run a cleanup command or just let it be destroyed
cmd := sprite.CommandContext(ctx, "kill", "-TERM", "1") // send signal to init
_ = cmd.Run()
}
delete(e.proxies, instance.InstanceID)
e.logger.Info("sprite instance stopped",
zap.String("sprite", spriteName),
zap.String("instance_id", instance.InstanceID))
return nil
}
func (e *SpritesExecutor) RecoverInstances(ctx context.Context) ([]*ExecutorInstance, error) {
// Recovery strategy:
// 1. Load all executors_running with executor_backend="sprites"
// 2. For each, try to reconnect:
// a. Get API token from secrets
// b. Check sprite still exists (sprite.Command("echo", "alive"))
// c. Check agentctl is still running (health check via new proxy)
// d. If alive: set up port forwarding, return recovered instance
// e. If dead: return nil (lifecycle manager will clean up)
e.logger.Info("recovering sprites instances")
// Note: actual recovery requires DB access which is done by the lifecycle manager.
// This method handles re-establishing connections to known-alive sprites.
// The lifecycle manager calls this after loading ExecutorRunning records.
return nil, nil // Sprites are ephemeral — recovery is best-effort
}
func (e *SpritesExecutor) GetInteractiveRunner() *process.InteractiveRunner {
return nil // No passthrough mode for remote sprites
}
// getFreePort returns an available TCP port on localhost.
func getFreePort() (int, error) {
listener, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
return 0, err
}
port := listener.Addr().(*net.TCPAddr).Port
_ = listener.Close()
return port, nil
}
Sprites Environment Preparer: lifecycle/env_preparer_sprites.go
package lifecycle
import (
"context"
"fmt"
"os"
"path/filepath"
"strings"
sprites "github.com/superfly/sprites-go"
"go.uber.org/zap"
"github.com/kandev/kandev/internal/common/logger"
)
// SpritesEnvironmentPreparer sets up the sprite environment for agent execution.
type SpritesEnvironmentPreparer struct {
agentctlBinaryPath string // path to local agentctl binary to upload
logger *logger.Logger
}
func NewSpritesEnvironmentPreparer(
agentctlBinaryPath string,
log *logger.Logger,
) *SpritesEnvironmentPreparer {
return &SpritesEnvironmentPreparer{
agentctlBinaryPath: agentctlBinaryPath,
logger: log.WithFields(zap.String("preparer", "sprites")),
}
}
func (p *SpritesEnvironmentPreparer) Prepare(
ctx context.Context,
req *EnvPrepareRequest,
) error {
spriteName := req.Instance.RemoteID
proxy := req.Instance.Metadata["_sprites_proxy"].(*SpritesProxy)
sprite := proxy.client.Sprite(spriteName)
steps := []struct {
name string
fn func() error
}{
{"install-system-deps", func() error { return p.installSystemDeps(ctx, sprite) }},
{"install-node", func() error { return p.installNode(ctx, sprite) }},
{"install-agent", func() error { return p.installAgent(ctx, sprite, req.AgentConfig) }},
{"upload-agentctl", func() error { return p.uploadAgentctl(ctx, sprite) }},
{"setup-workspace", func() error { return p.setupWorkspace(ctx, sprite, req.WorkspacePath) }},
{"copy-configs", func() error { return p.copyConfigs(ctx, sprite, req) }},
{"start-agentctl", func() error { return p.startAgentctl(ctx, sprite, req) }},
}
for _, step := range steps {
p.logger.Info("sprite prep step",
zap.String("step", step.name),
zap.String("sprite", spriteName))
if err := step.fn(); err != nil {
return fmt.Errorf("sprite prep %s: %w", step.name, err)
}
p.logger.Info("sprite prep step complete",
zap.String("step", step.name),
zap.String("sprite", spriteName))
}
return nil
}
func (p *SpritesEnvironmentPreparer) installSystemDeps(
ctx context.Context,
sprite sprites.Sprite,
) error {
cmd := sprite.CommandContext(ctx, "sh", "-c",
"apt-get update -qq && apt-get install -y -qq git curl ca-certificates")
output, err := cmd.CombinedOutput()
if err != nil {
p.logger.Error("install system deps failed", zap.String("output", string(output)))
return fmt.Errorf("install deps: %w", err)
}
return nil
}
func (p *SpritesEnvironmentPreparer) installNode(
ctx context.Context,
sprite sprites.Sprite,
) error {
// Install Node.js via NodeSource or fnm
script := `
if command -v node >/dev/null 2>&1; then
echo "node already installed: $(node --version)"
exit 0
fi
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt-get install -y -qq nodejs
echo "node installed: $(node --version)"
`
cmd := sprite.CommandContext(ctx, "sh", "-c", script)
output, err := cmd.CombinedOutput()
if err != nil {
p.logger.Error("install node failed", zap.String("output", string(output)))
return fmt.Errorf("install node: %w", err)
}
p.logger.Debug("node installation", zap.String("output", string(output)))
return nil
}
func (p *SpritesEnvironmentPreparer) installAgent(
ctx context.Context,
sprite sprites.Sprite,
agentConfig agents.Agent,
) error {
// Install the agent CLI based on agent type
// This uses the agent's InstallCommand from the registry
installCmd := agentConfig.InstallCommand
if installCmd == "" {
p.logger.Info("no install command for agent, skipping",
zap.String("agent", agentConfig.Name))
return nil
}
cmd := sprite.CommandContext(ctx, "sh", "-c", installCmd)
output, err := cmd.CombinedOutput()
if err != nil {
p.logger.Error("install agent failed",
zap.String("agent", agentConfig.Name),
zap.String("output", string(output)))
return fmt.Errorf("install agent %s: %w", agentConfig.Name, err)
}
return nil
}
func (p *SpritesEnvironmentPreparer) uploadAgentctl(
ctx context.Context,
sprite sprites.Sprite,
) error {
// Upload the agentctl binary to the sprite
// Strategy: pipe binary via stdin to a cat > /usr/local/bin/agentctl command
binaryData, err := os.ReadFile(p.agentctlBinaryPath)
if err != nil {
return fmt.Errorf("read agentctl binary: %w", err)
}
cmd := sprite.CommandContext(ctx, "sh", "-c",
"cat > /usr/local/bin/agentctl && chmod +x /usr/local/bin/agentctl")
stdin, err := cmd.StdinPipe()
if err != nil {
return fmt.Errorf("stdin pipe: %w", err)
}
if err := cmd.Start(); err != nil {
return fmt.Errorf("start upload: %w", err)
}
if _, err := stdin.Write(binaryData); err != nil {
return fmt.Errorf("write binary: %w", err)
}
if err := stdin.Close(); err != nil {
return fmt.Errorf("close stdin: %w", err)
}
if err := cmd.Wait(); err != nil {
return fmt.Errorf("upload agentctl: %w", err)
}
// Verify
verifyCmd := sprite.CommandContext(ctx, "agentctl", "--version")
output, err := verifyCmd.Output()
if err != nil {
return fmt.Errorf("verify agentctl: %w", err)
}
p.logger.Info("agentctl uploaded", zap.String("version", strings.TrimSpace(string(output))))
return nil
}
func (p *SpritesEnvironmentPreparer) setupWorkspace(
ctx context.Context,
sprite sprites.Sprite,
workspacePath string,
) error {
// Clone the repository into /workspace
// The repo URL and credentials come from the workspace config
script := fmt.Sprintf(`
mkdir -p /workspace
if [ -d /workspace/.git ]; then
echo "workspace already initialized"
exit 0
fi
cd /workspace
git init
echo "workspace initialized at /workspace"
`)
cmd := sprite.CommandContext(ctx, "sh", "-c", script)
output, err := cmd.CombinedOutput()
if err != nil {
p.logger.Error("setup workspace failed", zap.String("output", string(output)))
return fmt.Errorf("setup workspace: %w", err)
}
return nil
}
func (p *SpritesEnvironmentPreparer) copyConfigs(
ctx context.Context,
sprite sprites.Sprite,
req *EnvPrepareRequest,
) error {
// Copy configuration files from local machine to sprite
if req.CopyGitConfig {
if err := p.copyFileToSprite(ctx, sprite,
filepath.Join(os.Getenv("HOME"), ".gitconfig"),
"/root/.gitconfig"); err != nil {
p.logger.Warn("copy .gitconfig failed", zap.Error(err))
// Non-fatal
}
}
if req.CopyGHAuth {
// Copy gh CLI auth
ghConfigDir := filepath.Join(os.Getenv("HOME"), ".config", "gh")
if err := p.copyFileToSprite(ctx, sprite,
filepath.Join(ghConfigDir, "hosts.yml"),
"/root/.config/gh/hosts.yml"); err != nil {
p.logger.Warn("copy gh auth failed", zap.Error(err))
}
}
if req.CopyAgentConfig {
// Copy agent-specific config (e.g., ~/.claude for Claude Code)
// This depends on the agent type
agentConfigPaths := req.AgentConfig.ConfigPaths
for _, path := range agentConfigPaths {
localPath := filepath.Join(os.Getenv("HOME"), path)
remotePath := filepath.Join("/root", path)
if err := p.copyFileToSprite(ctx, sprite, localPath, remotePath); err != nil {
p.logger.Warn("copy agent config failed",
zap.String("path", path), zap.Error(err))
}
}
}
return nil
}
func (p *SpritesEnvironmentPreparer) copyFileToSprite(
ctx context.Context,
sprite sprites.Sprite,
localPath, remotePath string,
) error {
data, err := os.ReadFile(localPath)
if err != nil {
return fmt.Errorf("read %s: %w", localPath, err)
}
// Create parent directory
dir := filepath.Dir(remotePath)
mkdirCmd := sprite.CommandContext(ctx, "mkdir", "-p", dir)
if err := mkdirCmd.Run(); err != nil {
return fmt.Errorf("mkdir %s: %w", dir, err)
}
// Write file via stdin pipe
cmd := sprite.CommandContext(ctx, "sh", "-c", fmt.Sprintf("cat > %s", remotePath))
stdin, err := cmd.StdinPipe()
if err != nil {
return err
}
if err := cmd.Start(); err != nil {
return err
}
if _, err := stdin.Write(data); err != nil {
return err
}
_ = stdin.Close()
return cmd.Wait()
}
func (p *SpritesEnvironmentPreparer) startAgentctl(
ctx context.Context,
sprite sprites.Sprite,
req *EnvPrepareRequest,
) error {
// Start agentctl as a background service in the sprite
// Using the Sprites services API for long-running processes
//
// Note: We could also use sprite.Command with Start() (no Wait()),
// but using the services API gives us better lifecycle management.
envVars := make([]string, 0)
for k, v := range req.Instance.Metadata {
if strings.HasPrefix(k, "env_") {
envVars = append(envVars, fmt.Sprintf("%s=%s", strings.TrimPrefix(k, "env_"), v))
}
}
cmd := sprite.CommandContext(ctx, "agentctl",
"--port", fmt.Sprintf("%d", spritesAgentctlPort),
"--workspace", "/workspace",
)
cmd.Env = envVars
if err := cmd.Start(); err != nil {
return fmt.Errorf("start agentctl: %w", err)
}
// Don't Wait() — agentctl runs as a long-lived process.
// Port forwarding will connect to it.
// Give agentctl a moment to start listening
// Then verify with a health check
// (the actual health check happens via the port-forwarded connection
// after CreateInstance returns)
return nil
}
func (p *SpritesEnvironmentPreparer) Cleanup(
ctx context.Context,
instanceID string,
) error {
// Cleanup is handled by SpritesExecutor.StopInstance which destroys the sprite
return nil
}
agentctl Deployment & Connection
Binary Deployment Strategy
┌─────────────────────────────────────────────────────────────────┐
│ agentctl Binary Deployment │
│ │
│ Option A: Upload local binary (primary) │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 1. Read agentctl binary from known path │ │
│ │ (compiled for linux/amd64, same as backend binary) │ │
│ │ 2. Pipe to sprite via stdin: cat > /usr/local/bin/... │ │
│ │ 3. chmod +x │ │
│ │ 4. Verify: agentctl --version │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ Option B: Download from release (fallback) │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 1. curl agentctl binary from release URL │ │
│ │ 2. Install to /usr/local/bin/agentctl │ │
│ │ 3. Verify version │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ Config: agentctl binary path set in backend config │
│ e.g., KANDEV_AGENTCTL_BINARY=/usr/local/bin/agentctl │
│ or automatically detected relative to kandev binary │
└─────────────────────────────────────────────────────────────────┘
Port Forwarding Architecture
┌──────────────────────┐ ┌──────────────────────┐
│ Kandev Backend │ │ Sprite (remote) │
│ │ │ │
│ agentctl.Client │ │ agentctl process │
│ → 127.0.0.1:49152 │ │ listening :8765 │
│ │ │ │ ▲ │
│ ▼ │ │ │ │
│ ┌──────────────┐ │ │ ┌────────────┐ │
│ │ Local TCP │ │ WSS │ │ TCP │ │
│ │ Socket │◄───┼──tunnel──┼───►│ Socket │ │
│ │ :49152 │ │ (sprites │ │ :8765 │ │
│ └──────────────┘ │ SDK) │ └────────────┘ │
│ │ │ │
└──────────────────────┘ └──────────────────────┘
sprites.ProxyPort(ctx, 49152, 8765)
- Establishes WebSocket tunnel to sprites API
- All TCP traffic on localhost:49152 is tunneled to sprite:8765
- Transparent to agentctl.Client — just connects to localhost port
Connection Lifecycle
1. CreateInstance:
- Create sprite
- Start agentctl inside sprite on port 8765
- Find free local port (e.g., 49152)
- Start ProxyPort() goroutine (long-lived)
- Create agentctl.Client pointing to 127.0.0.1:49152
- Return ExecutorInstance with client
2. During session:
- agentctl.Client sends HTTP/WS requests to 127.0.0.1:49152
- Sprites SDK tunnels these to sprite:8765
- agentctl process handles requests, manages agent subprocess
3. StopInstance:
- Cancel ProxyPort context (closes tunnel)
- Destroy sprite via API
- Clean up proxy state
4. Error handling:
- If tunnel drops: health check detects, marks unhealthy
- If sprite dies: health check detects, lifecycle manager handles cleanup
- If backend restarts: recovery attempts to re-establish tunnels
Session Resume & Recovery
Recovery Flow
Backend Restart
│
▼
┌─────────────────────────────────────────────────────────────┐
│ SpritesExecutor.RecoverInstances() │
│ │
│ 1. Read SPRITES_API_TOKEN from secrets │
│ 2. List sprites with prefix "kandev-" │
│ GET /v1/sprites (filter by name prefix) │
│ │
│ 3. For each sprite: │
│ a. Match to executors_running record by remote_id │
│ b. Check sprite health: sprite.Command("echo", "alive") │
│ c. Check agentctl health: sprite.Command("curl", │
│ "http://localhost:8765/health") │
│ d. If both healthy: │
│ - Find free local port │
│ - Start ProxyPort() │
│ - Create agentctl.Client │
│ - Return recovered ExecutorInstance │
│ e. If unhealthy: │
│ - Log details │
│ - Skip (lifecycle manager marks session as failed) │
│ - Optionally destroy dead sprite │
└─────────────────────────────────────────────────────────────┘
Health Check for Sprites
func (e *SpritesExecutor) healthCheckSprite(ctx context.Context, proxy *SpritesProxy) error {
// Two-level health check:
// Level 1: Can we reach the sprite?
cmd := proxy.sprite.CommandContext(ctx, "echo", "alive")
if _, err := cmd.Output(); err != nil {
return fmt.Errorf("sprite unreachable: %w", err)
}
// Level 2: Is agentctl responding?
cmd = proxy.sprite.CommandContext(ctx, "curl", "-sf",
fmt.Sprintf("http://localhost:%d/health", spritesAgentctlPort))
if _, err := cmd.Output(); err != nil {
return fmt.Errorf("agentctl not responding: %w", err)
}
return nil
}
Settings Page
Sprites Settings UI
┌──────────────────────────────────────────────────────────────────┐
│ Sprites.dev Integration │
│──────────────────────────────────────────────────────────────────│
│ │
│ ┌─── Connection ──────────────────────────────────────────────┐ │
│ │ │ │
│ │ API Token: ●●●●●●●●●●●●●●●●●●●●●● [Reveal] [Change] │ │
│ │ Status: ● Connected │ │
│ │ │ │
│ │ [Test Connection] │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─── Default Network Policies ────────────────────────────────┐ │
│ │ │ │
│ │ Allowed domains (one per line): │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ *.npm.org │ │ │
│ │ │ *.github.com │ │ │
│ │ │ *.githubusercontent.com │ │ │
│ │ │ registry.npmjs.org │ │ │
│ │ │ pypi.org │ │ │
│ │ │ *.anthropic.com │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ │ [Save] │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─── Environment Setup ───────────────────────────────────────┐ │
│ │ │ │
│ │ ☑ Copy agent config/auth files from local │ │
│ │ ☑ Copy gh CLI auth token for git operations │ │
│ │ ☑ Copy .gitconfig │ │
│ │ ☐ Custom setup script (advanced) │ │
│ │ │ │
│ │ [Save Defaults] │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─── Running Sprites ─────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
│ │ │ kandev-abc12345 │ │ │
│ │ │ Session: Fix login bug • Running 2h 15m │ │ │
│ │ │ Health: ● healthy [Destroy] │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
│ │ │ kandev-def67890 │ │ │
│ │ │ Session: Refactor auth • Running 45m │ │ │
│ │ │ Health: ● healthy [Destroy] │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Total: 2 sprites running [Destroy All] │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘
Settings Data Model
// SpritesSettings stored in the executor profile config
type SpritesProfileConfig struct {
APITokenSecretID string `json:"api_token_secret_id"`
NetworkPolicies []string `json:"network_policies"`
CopyGHAuth bool `json:"copy_gh_auth"`
CopyGitConfig bool `json:"copy_git_config"`
CopyAgentConfig bool `json:"copy_agent_config"`
CustomSetupScript string `json:"custom_setup_script,omitempty"`
}
Debug & Test Harness
Structured Logging
All sprites operations use structured logging with consistent fields:
// Logger fields for all sprites operations
zap.String("executor", "sprites")
zap.String("sprite", spriteName)
zap.String("session_id", sessionID)
zap.String("step", stepName) // prep step name
zap.Duration("elapsed", duration) // step duration
// Example log output:
// INFO sprites executor: creating sprite sprite=kandev-abc12345 session_id=sess-abc
// INFO sprites prep: install-system-deps sprite=kandev-abc12345 elapsed=12.3s
// INFO sprites prep: install-node sprite=kandev-abc12345 elapsed=8.1s
// INFO sprites prep: install-agent sprite=kandev-abc12345 elapsed=15.7s
// INFO sprites prep: upload-agentctl sprite=kandev-abc12345 elapsed=2.1s
// INFO sprites prep: setup-workspace sprite=kandev-abc12345 elapsed=0.3s
// INFO sprites prep: copy-configs sprite=kandev-abc12345 elapsed=1.2s
// INFO sprites prep: start-agentctl sprite=kandev-abc12345 elapsed=0.5s
// INFO sprites executor: instance created sprite=kandev-abc12345 local_port=49152 total=40.2s
Test Harness: CLI Command
// cmd/kandev/sprites_test_harness.go (or a separate CLI command)
// Usage: kandev sprites-test --token <token> --agent claude-code
// Test harness steps:
// 1. Create a sprite
// 2. Run environment preparation (all steps)
// 3. Start agentctl
// 4. Establish port forwarding
// 5. Send health check via agentctl client
// 6. Send a simple prompt (e.g., "echo hello")
// 7. Wait for response
// 8. Destroy sprite
// 9. Report timing for each step
func runSpritesTestHarness(cfg SpritesTestConfig) error {
log := logger.New(logger.Debug) // verbose logging
fmt.Println("=== Sprites.dev Test Harness ===")
fmt.Println()
// Step 1: Create sprite
fmt.Print("1. Creating sprite... ")
start := time.Now()
client := sprites.New(cfg.Token)
spriteName := fmt.Sprintf("kandev-test-%d", time.Now().Unix())
sprite := client.Sprite(spriteName)
cmd := sprite.Command("echo", "ready")
if _, err := cmd.Output(); err != nil {
return fmt.Errorf("create sprite: %w", err)
}
fmt.Printf("OK (%s)\n", time.Since(start))
// Step 2-6: ... (similar pattern)
// Step 9: Report
fmt.Println()
fmt.Println("=== Results ===")
fmt.Printf("Total time: %s\n", totalDuration)
fmt.Printf("Sprite name: %s\n", spriteName)
fmt.Println("All steps passed!")
return nil
}
Test Harness API Endpoint
POST /api/v1/sprites/test
Request: { "token": "optional-override" } // uses stored token if not provided
Response: {
"success": true,
"steps": [
{ "name": "create_sprite", "duration_ms": 2340, "success": true },
{ "name": "install_deps", "duration_ms": 12300, "success": true },
{ "name": "upload_agentctl", "duration_ms": 2100, "success": true },
{ "name": "health_check", "duration_ms": 150, "success": true },
{ "name": "cleanup", "duration_ms": 800, "success": true }
],
"total_duration_ms": 17690,
"sprite_name": "kandev-test-1708444800"
}
API Endpoints
Sprites-Specific Endpoints
| Method | Path | Description |
|---|---|---|
POST |
/api/v1/sprites/test |
Run test harness |
GET |
/api/v1/sprites/instances |
List running sprites |
DELETE |
/api/v1/sprites/instances/:name |
Destroy a sprite |
DELETE |
/api/v1/sprites/instances |
Destroy all sprites |
GET |
/api/v1/sprites/status |
Check API connection status |
WebSocket Actions
| Action | Payload | Description |
|---|---|---|
sprites.test |
{} |
Run test harness |
sprites.instances.list |
{} |
List running sprites |
sprites.instances.destroy |
{name} |
Destroy sprite |
sprites.instances.destroy_all |
{} |
Destroy all |
sprites.status |
{} |
Connection status |
Frontend Implementation
New Files
apps/web/
├── app/settings/sprites/
│ └── page.tsx # Sprites settings route
├── components/settings/
│ └── sprites-settings-page.tsx # Sprites settings page
├── lib/api/domains/
│ └── sprites-api.ts # Sprites API client
├── lib/types/
│ └── http-sprites.ts # Sprites types
└── hooks/domains/settings/
└── use-sprites.ts # Sprites data hooks
TypeScript Types: lib/types/http-sprites.ts
export interface SpritesInstance {
name: string;
session_id?: string;
task_title?: string;
health_status: 'healthy' | 'unhealthy' | 'unknown';
created_at: string;
uptime_seconds: number;
}
export interface SpritesStatus {
connected: boolean;
token_configured: boolean;
instance_count: number;
}
export interface SpritesTestResult {
success: boolean;
steps: SpritesTestStep[];
total_duration_ms: number;
sprite_name: string;
error?: string;
}
export interface SpritesTestStep {
name: string;
duration_ms: number;
success: boolean;
error?: string;
output?: string;
}
Settings Sidebar Addition
// In settings-app-sidebar.tsx, under "Integrations" section:
{
title: "Integrations",
items: [
{ title: "Sprites.dev", url: "/settings/sprites", icon: IconSparkles },
// future: { title: "exe.dev", url: "/settings/exedev", icon: ... },
]
}
Error Handling & Edge Cases
Common Failure Modes
┌────────────────────────────────────┬─────────────────────────────────────┐
│ Failure │ Handling │
├────────────────────────────────────┼─────────────────────────────────────┤
│ Invalid API token │ Error at HealthCheck, clear message │
│ │ "Sprites API token invalid or │
│ │ expired. Check Settings > Sprites." │
├────────────────────────────────────┼─────────────────────────────────────┤
│ Sprite creation fails │ Retry once, then fail with │
│ (API rate limit, quota) │ actionable error message │
├────────────────────────────────────┼─────────────────────────────────────┤
│ Node.js install fails │ Log full output, fail prep step │
│ │ with details for debugging │
├────────────────────────────────────┼─────────────────────────────────────┤
│ Agent CLI install fails │ Log output, suggest checking │
│ │ agent availability / network policy │
├────────────────────────────────────┼─────────────────────────────────────┤
│ agentctl upload fails │ Check binary path config, │
│ (binary not found) │ suggest rebuilding agentctl │
├────────────────────────────────────┼─────────────────────────────────────┤
│ Port forwarding drops │ Health check detects, marks │
│ │ unhealthy, attempts reconnect │
├────────────────────────────────────┼─────────────────────────────────────┤
│ Sprite dies unexpectedly │ Health check detects, session │
│ │ marked as failed, cleanup │
├────────────────────────────────────┼─────────────────────────────────────┤
│ Network policy blocks agent │ Agent fails to call API, │
│ API calls │ suggest adding domain to policies │
├────────────────────────────────────┼─────────────────────────────────────┤
│ Backend restart with running │ Recovery flow: list sprites, │
│ sprites │ health check, reconnect or cleanup │
├────────────────────────────────────┼─────────────────────────────────────┤
│ Concurrent sprite limit │ Show error with current count and │
│ (user's account quota) │ link to running sprites list │
└────────────────────────────────────┴─────────────────────────────────────┘
Timeout Configuration
const (
spriteCreateTimeout = 60 * time.Second
spriteStepTimeout = 120 * time.Second // per prep step
spriteTotalPrepTimeout = 10 * time.Minute // total prep time
spriteHealthTimeout = 10 * time.Second
spriteDestroyTimeout = 30 * time.Second
)
Cleanup on Failure
// If any step fails during CreateInstance or Prepare:
// 1. Log the failure with full context
// 2. Attempt to destroy the sprite (best effort)
// 3. Clean up local port forwarding
// 4. Return error to lifecycle manager
// 5. Lifecycle manager emits session error event
func (e *SpritesExecutor) cleanupOnFailure(ctx context.Context, spriteName string, instanceID string) {
// Best-effort cleanup — don't fail if cleanup itself fails
if proxy, ok := e.proxies[instanceID]; ok {
proxy.cancelFn()
delete(e.proxies, instanceID)
}
// Try to destroy the sprite
// (sprite may not exist if creation itself failed)
e.logger.Info("cleaning up failed sprite",
zap.String("sprite", spriteName))
}
Files Changed Summary
New Files
| File | Description |
|---|---|
apps/backend/internal/agent/lifecycle/executor_sprites.go |
SpritesExecutor backend |
apps/backend/internal/agent/lifecycle/env_preparer_sprites.go |
Sprites environment preparer |
apps/backend/internal/sprites/settings.go |
Sprites settings service |
apps/backend/internal/sprites/handlers.go |
Sprites API handlers |
apps/web/app/settings/sprites/page.tsx |
Route page |
apps/web/components/settings/sprites-settings-page.tsx |
Settings page component |
apps/web/lib/api/domains/sprites-api.ts |
API client |
apps/web/lib/types/http-sprites.ts |
TypeScript types |
apps/web/hooks/domains/settings/use-sprites.ts |
Data hooks |
Modified Files
| File | Change |
|---|---|
apps/backend/cmd/kandev/agents.go |
Register SpritesExecutor + preparer |
apps/backend/cmd/kandev/routes.go |
Register sprites API routes |
apps/backend/go.mod |
Add github.com/superfly/sprites-go dependency |
apps/backend/internal/agent/executor/executor.go |
Add NameSprites constant |
apps/backend/internal/task/models/models.go |
Add ExecutorTypeSprites constant |
apps/backend/internal/task/repository/sqlite/defaults.go |
Default sprites executor + profile |
apps/web/lib/executor-icons.ts |
Add sprites icon |
apps/web/components/settings/settings-app-sidebar.tsx |
Add Sprites nav item |
Dependencies
| Dependency | Purpose |
|---|---|
github.com/superfly/sprites-go |
Sprites.dev Go SDK |
Implementation Order
- Add sprites-go dependency —
go get github.com/superfly/sprites-go - SpritesExecutor skeleton — implement interface with stub methods
- Environment preparer — step-by-step sprite setup
- agentctl deployment — binary upload + launch
- Port forwarding — ProxyPort integration
- Recovery — list + reconnect sprites on restart
- Settings page — frontend for API key, policies, running sprites
- Test harness — CLI + API endpoint for end-to-end testing
- Health checks — integrate with health loop from Plan 02
- Polish — error messages, timeouts, cleanup
Last updated: 2026-02-20