Agent Architecture

Diagram

The diagram below captures the current high-level architecture for a Ikidna agent runtime.

flowchart TD
    Runtime
    Workspace[Workspace]
    Volumes
    Config[Configuration\nOpencode config etc]
    Harness
    Tools[Tools\nBinaries]
    Skills[Skills]
    Model[Model]
    MCP[MCP]
    Telemetry[Telemetry]

    Runtime --> Workspace
    Runtime --> Harness

    Workspace --> Volumes
    Workspace --> Config
    Workspace --> Tools
    Workspace --> Skills

    Harness --> Tools
    Harness --> Skills
    Harness --> Model
    Harness --> MCP
    Harness --> Telemetry

Component Mapping

Runtime: Execution substrate that hosts the agent runtime and workspace. It may be a local process host, a shared VM, or a fully isolated cloud sandbox depending on deployment mode. This is likely a Pod / VM
Workspace: Mutable task context where code, prompts, artifacts, and temporary state are handled. This will be a file system where the agent has access. Generally this is a git worktree when the execution is on a users local machine.
Volumes / Persistent storage: Durable storage boundary for long-lived state. There can also be additional volumes alongside the active workspace. These could be shared between other agents. A good example is mounting a readonly volume that might contain config
Configuration: Harness and runtime configuration (for example, OpenCode settings). This is likely to be readonly.
Harness: Agent control loop and tool mediation layer. See Harnesses.
Tools / Binaries: External executables and automation tools the harness can invoke. This is normally exposed by letting a harness run bash directly
Skills: Reusable behavior packages and constraints. See Skills.
Model: LLM endpoint(s) selected by routing and policy.
MCP: Standardized tool and service integration channel. See MCP
Telemetry: Execution events, traces, and cost signals that should flow into the Execution Ledger.

Deployment Modes: Local-First vs Cloud-First

Contrast Summary

Dimension	Local-First	Cloud-First (Isolated Agent)	Cloud-First (Shared VM, Multi-Agent)
Context boundary	Shared machine context by default	Per-agent isolated sandbox	Shared VM baseline, per-agent workspace isolation
Filesystem assumptions	Agents can often read/write common local paths	Agent only sees mounted workspace and explicit volumes	Agents share VM resources; must enforce per-workspace boundaries
Coordination model	Implicit via shared environment and local state	Explicit via orchestrator, queues, and artifacts	Mixed: explicit orchestration plus optional shared caches
Security posture	Weaker isolation unless extra sandboxing is added	Strong isolation and blast-radius control	Better density, but stronger policy controls required
Cost profile	Lower infra overhead, higher risk of state coupling	Higher infra overhead, cleaner tenancy	Balanced compute efficiency with medium isolation
Typical use	Solo/dev loop, fast iteration	Production autonomous execution	Swarm-style execution on pooled compute

Operational Notes

Local-first assumption: a single machine can act as a shared context surface, so agents may depend on local process state, filesystem state, and long-lived caches.
Cloud-first isolated assumption: each agent is treated as disposable and self-contained, with no implicit shared state beyond explicit external systems.
Cloud-first shared VM option: multiple agents can run in one VM for efficiency, but each agent should still use isolated workspaces and policy-enforced tool scopes.
Adapter requirement: Ikidna must provide pluggable runtime adapters that support all operational types (local-first, cloud-isolated, and cloud shared-VM) behind a common orchestration interface.
Ikidna implication: the orchestration layer should treat shared state as optional and model explicit edges in the execution ledger for every cross-agent dependency.

Deployment View

flowchart LR
    subgraph LocalFirst[Local-First]
        LHost[Single Machine]
        LAgent1[Agent A]
        LAgent2[Agent B]
        LShared[Shared local context\nFS, cache, processes]
        LHost --> LAgent1
        LHost --> LAgent2
        LAgent1 <--> LShared
        LAgent2 <--> LShared
    end

    subgraph CloudIsolated[Cloud-First Isolated]
        COrch[Orchestrator]
        CIsoA[VM/Pod Agent A]
        CIsoB[VM/Pod Agent B]
        CExt[External systems\nledger, storage, queues]
        COrch --> CIsoA
        COrch --> CIsoB
        CIsoA --> CExt
        CIsoB --> CExt
    end

    subgraph CloudShared[Cloud-First Shared VM]
        SVM[Shared VM]
        SAgent1[Agent A workspace]
        SAgent2[Agent B workspace]
        SPolicy[Policy + isolation guardrails]
        SVM --> SAgent1
        SVM --> SAgent2
        SPolicy --> SAgent1
        SPolicy --> SAgent2
    end

Why This Matters

This view makes the harness a first-class architectural boundary. It clarifies where to enforce policy, where observability should be captured, and where progressive enrichment can be attached without tightly coupling Ikidna to a single harness or model provider.