OSA Framework

OSA is a filesystem-first framework for making your own agents on MIOSA.

Package: @miosa/osa

Repository: Miosa-osa/osa-framework

Standard Start

One file is enough:

my-agent/
  agent/
    instructions.md

Create it:

npx @miosa/osa init my-agent
cd my-agent

Write what your agent should do:

# Instructions

You are a customer research agent.

Find primary sources, summarize the important facts, and ask for approval before
contacting anyone or changing external systems.

Build the manifest:

npx @miosa/osa build

That is the standard path. Add tools, skills, subagents, schedules, channels, Computers, docs, and evals only when the agent actually needs them.

Read the full standard: docs/standard.md.

Grow The Agent

When the one-file agent needs more structure, keep growing the agent/ directory:

my-agent/
  agent/
    AGENTS.md
    agent.ts
    instructions.md
    permissions.yml
    computers/
    connections/
    channels/
    schedules/
    docs/
    skills/
    subagents/
    tools/
  evals/

Use templates when you want a prepared shape:

npx @miosa/osa init my-agent --template full
npx @miosa/osa init browser-agent --template browser-qa
npx @miosa/osa init repo-agent --template repo-maintainer
npx @miosa/osa init deploy-agent --template deployment-operator

List templates:

npx @miosa/osa templates

Run Or Deploy On MIOSA

After building, use the MIOSA CLI:

miosa osa publish --workspace <workspace-id>
miosa osa deploy --workspace <workspace-id> --wait
miosa osa run "inspect this repo" --sandbox <sandbox-id>
miosa osa run "validate the browser workflow" --computer <computer-id>

agent/agent.ts declares the agent operating profile. The framework compiles that profile into the manifest; the MIOSA CLI/backend use it as the default for run and deploy unless a CLI flag overrides it.

import { defineAgent } from "@miosa/osa";

export default defineAgent({
  model: {
    primary: "openai/gpt-5",
    fallback: ["anthropic/claude-sonnet-4.6"],
  },
  harness: {
    engine: "auto",
    allowed: ["codex", "claude-code", "hermes", "osa"],
  },
  runtime: {
    target: "miosa-cloud",
    durability: "checkpointed",
    streaming: true,
  },
  sandbox: {
    backend: "auto",
    allowed: ["miosa-computer", "miosa-sandbox", "local-docker"],
  },
});

Why OSA

Filesystem-first agents are easier to inspect, review, test, and operate. OSA uses that authoring model, but targets MIOSA platform primitives:

• Computers and browser-capable desktop automation
• OpenComputers and BYOC runtime targets
• Persistent sandboxes and workspace state
• Durable deployment records through miosa osa deploy
• Runtime profiles that separate model routing, harness engine, compute backend, durability, and policy
• Skills, tools, subagents, schedules, channels, root-level evals, docs, and approvals
• White-label deployments where the agent runs inside customer-facing products

Commands

osa init [target]
osa init [target] --template repo-maintainer
osa info [target]
osa build [target]
osa skills [target]
osa docs
osa templates

osa docs prints the bundled documentation path. Coding agents can read those files from node_modules/@miosa/osa/docs after installation.

Standards

Read docs/standards.md before publishing a serious OSA project. It defines the expected bar for instructions, tools, skills, subagents, permissions, evals, schedules, channels, examples, and deployment readiness.

Examples

Real examples live in examples/:

• examples/minimal-agent: the one-file starter example for people making their own agent.
• examples/standard-agent: full standard weather agent with instructions, model config, skill, tool, sandbox, channel, connection, subagent, schedule, and eval.
• examples/browser-qa-agent: focused browser workflow QA agent using MIOSA Computer capabilities.
• examples/clinic-ops-agent: operational support agent with browser QA, schedule, GitHub/MCP connection, approvals, and a specialist investigator subagent.
• examples/repo-maintainer-agent: engineering agent for PR review, CI triage, release notes, and issue maintenance.
• examples/deployment-operator-agent: production rollout, smoke check, rollback, and incident handoff agent.

Built-in templates:

• standard
• full
• browser-qa
• clinic-ops
• repo-maintainer
• deployment-operator

Compatibility alias: default maps to standard.

Legacy compatibility: existing projects with osa/ still inspect and build, but new projects should use agent/.

Library

import { initProject, inspectProject, buildProject } from "@miosa/osa";

await initProject("my-agent");
const project = inspectProject("my-agent");
const build = buildProject("my-agent");

Status

This package is the standalone framework authoring surface. Runtime dispatch, tenant auth, Computer execution, and deployment are provided by the MIOSA platform and the miosa CLI.