Phantasy

Phantasy lets you build an AI companion/VTuber who can run her own APIs, CMS, content, workflows, and business.

Think WordPress for AI companions: an installable open-source agent framework/CMS for characterized AI companions and companion-native products.

Build one character who can chat, publish, remember, automate, and run the CMS, APIs, workflows, and business around that character from the same runtime architecture. The terminal, admin shell, headless content APIs, and workflow system are operator surfaces around that character.

Core thesis: AI companions are an operating-system problem, not only an agent-framework problem.

Where It Fits

Phantasy is the useful runtime layer in a wider stack:

• Phantasy: the one-runtime companion OS for character identity, site, workflows, and business around one deployment
• Alkahest: the shared trust-rail layer below Phantasy for hosted inference, provider routing, attestation, and shared payment rails
• Party Quest: the multi-runtime orchestration layer above Phantasy for cross-agent routing, oversight, and group-level approvals

Phantasy is therefore not a generic agent protocol, not a trustless verification layer by itself, and not the default multi-agent control plane.

Product Boundary

Phantasy owns the one-runtime character operating system:

• one companion runtime
• native bounded subagents for local fanout under that runtime
• the five workspaces: Character, Site, Business, Workflows, and Operations
• the admin shell, CLI, workflow system, and operating surfaces around one deployment

Phantasy is not the shared trust-rail layer, it is not the multi-runtime control plane, and it is not the consumer product itself.

• shared hosted inference, provider routing, attestation, and shared payment rails can live below it in Alkahest
• product-specific affection, inventory, date mechanics, and launch gating can live above it in Rally until they prove reusable
• Party Quest is the adjacent many-runtime control plane, not the default Phantasy story
• Boss Raid is the future marketplace/external-agent sourcing layer, not part of the native Phantasy subagent runtime

Show It In This Order

When you demo or explain the flagship product, keep usefulness ahead of economics:

1. the public-facing companion
2. the site or published content surface
3. memory or continuity inside the same runtime
4. an approval-gated workflow or operator loop
5. a business or integration action

Fastest Path

Requirements:

• Node.js 22.12+

Zero-install first run:

npx -y @phantasy/agent init my-brand   # selected skills/workflows auto-installed on first run
npx -y @phantasy/agent run --config config/agents/my-brand.json

Then open:

• admin shell: http://localhost:2000/admin
• API/server: http://localhost:2000

Default path: init -> run -> open the admin shell.

The Site workspace is a headless CMS. Phantasy stores, reviews, publishes, and serves content APIs; your public site or app can be any frontend stack that reads /api/content/*. This repo also includes a non-shipped reference Astro frontend under site/ for local dogfooding (bun run dev:site). External starters live in templates/site-frontend-starter/ and phantasy-bot/examples; Phantasy does not ship installable themes or a WordPress-style frontend package.

Forkable example apps live outside this release repo in phantasy-bot/examples, including Next.js, Astro/SvelteKit, and companion-product apps such as the Rally-style integration surface we dogfood against the same content APIs.

Optional terminal chat:

npx -y @phantasy/agent chat --config config/agents/my-brand.json

Health check:

npx -y @phantasy/agent doctor --config config/agents/my-brand.json

Doctor verifies the runtime config, local environment, product workspace briefs, 2D/3D avatar asset readiness, coding-agent readiness, and live health endpoint. If local scaffold files are missing, run:

npx -y @phantasy/agent doctor --config config/agents/my-brand.json --repair-scaffold

phantasy init creates the flagship runtime config and a Convex quickstart .env in the current workspace. Run ./scripts/convex-bootstrap.sh once to start self-hosted Convex and obtain an admin key. First local login uses the bootstrap admin account on localhost. On first startup, rotate that password and generate real auth secrets before widening access.

Quickstart safety contract:

• bootstrap auth is only for loopback-only localhost use
• rotate the bootstrap admin password and auth secrets in onboarding immediately
• do not switch to non-loopback hosts, shared origins, or public exposure until rotation is complete

Deploy

Phantasy supports local-first setup and hosted deployment as separate paths.

Path	Link	Status
Docker Compose	Deploy guide	supported self-host path
Railway	Railway guide	template + deploy button; rotate bootstrap secrets; not CI live-validated
Hetzner VPS	Hetzner guide	server-owned Docker Compose path
Phala TEE	Phala TEE guide	TDX attestation validation path
Phantasy Cloud	Phantasy Cloud	proprietary control plane in phantasy-bot/cloud

Local init uses self-hosted Convex by default (./scripts/convex-bootstrap.sh). Shared and production deployments should set CONVEX_SELF_HOSTED_URL and CONVEX_SELF_HOSTED_ADMIN_KEY (or Convex Cloud CONVEX_URL + CONVEX_DEPLOY_KEY).

Add Party Quest When You Need More Than One Runtime

Keep first success simple: get one Phantasy runtime working before adding a control plane.

Add Party Quest when you need a Paperclip-style operator layer for:

• multiple runtimes such as Phantasy, OpenClaw, Hermes, or AGENTS.md workspaces
• quests, blocker dependencies, runs, traces, approvals, budgets, and schedules
• execution workspace readiness and source-control handoff visibility
• operator review across a party, formation, campaign, or launch effort

If OpenClaw or Hermes are useful runtime/framework references and Paperclip is the operator-company control-plane reference, Phantasy plus Party Quest is the companion-native version of that stack: one strong runtime first, multi-runtime orchestration when needed.

Party Quest app checkout:

The apps/party-quest/ control plane is optional and gitignored in this OSS clone. Phantasy still ships the SDK, adapters, contract tests, and dogfood scripts under packages/party-quest-* and scripts/party-quest/. Clone or symlink the Party Quest app locally when you want the full control-plane UI and example projects. Set PHANTASY_INCLUDE_PARTY_QUEST_APP=1 to force quality:partyquest app checks when the directory is present.

Shortest Party Quest path (after apps/party-quest is available locally):

pnpm --dir apps/party-quest install
pnpm --dir apps/party-quest dev
npm run party-quest:onboard -- --agent companion

Then create one Party, one Agent, one Quest, send one heartbeat, and inspect the result in Activity.

What You Get

• one character runtime that resolves identity, logic, assets, and interactions across chat, scenes, site, and external shells
• versioned external APIs for character runtime metadata and integration chat
• a self-hosted operating system for AI companion businesses
• five workspaces: Character, Site, Business, Workflows, and Operations
• project-local workspace briefs: PRODUCT.md, character/CHARACTER.md, character/APPEARANCE.md, site/, business/, workflows/, and operations/
• markdown-first local development with Convex system storage and optional vector-backed memory
• headless content publishing APIs with workflows, approvals, memory, and extensions
• external frontend examples, not installable in-repo website themes or templates

Pick A Shape

The launch-front-door shape is companion. VTuber, NPC, and CMS paths are more specific presets or aliases layered around the same runtime family.

• companion: the generalized default runtime for companions and embodied AI characters
• vtuber: creator-specific runtime for VTubers, PNGTubers, and stream-native characters
• npc or character: the same companion runtime, named for NPC and embodied character creation
• cms: the same companion runtime, named for WordPress-style Site workspace work
• operator: workflows, approvals, and operational execution around the same companion
• developer or coder: local repo search, git review, tracked shell tasks, headless task/file APIs, and coding-agent flows

Examples:

npx -y @phantasy/agent init my-brand
npx -y @phantasy/agent init stream-studio --vtuber
npx -y @phantasy/agent init quest-giver --npc
npx -y @phantasy/agent init creator-site --cms
npx -y @phantasy/agent init ops-lead --operator
npx -y @phantasy/agent init repo-agent --coder

Use init for the full local quickstart env. Use create when you only need a runtime config plus the non-overwriting local workspace scaffold:

npx -y @phantasy/agent create companion my-brand
npx -y @phantasy/agent create agent --preset vtuber stream-studio
npx -y @phantasy/agent create npc quest-giver
npx -y @phantasy/agent create cms creator-site
npx -y @phantasy/agent create coder repo-agent

If the CLI is already on your PATH, you can drop the npx -y @phantasy/agent prefix and run phantasy ... directly.

Advanced Runtime Surfaces

For most teams, the answer is still @phantasy/agent. If you are following the flagship product path, you can stop at the quickstart, workspaces, and trust model sections.

Advanced package surfaces exist for narrower trust boundaries and embedding:

• flagship self-hosted OS: @phantasy/agent
• embedded runtime: @phantasy/agent-core
• optional operator surfaces: CLI, TUI, CMS APIs, and server-admin
• optional Party Quest collaboration for cross-agent or cross-business work later

Use @phantasy/agent-core when you are embedding Phantasy inside another host and want to own runtime bootstrap explicitly. Use @phantasy/agent when you want the full Phantasy bootstrap path, built-in provider wiring, and the flagship product surfaces.

Repo development:

bun install
./start.sh
phantasy gateway status

See env matrix for the full boot-path, env-file, and Convex matrix.

Gateway execution targets now include local, docker, singularity, modal, daytona, and ssh. In this repo, modal and daytona are wired through the runtime and covered by unit tests and typecheck, but they are not part of the default live smoke loop unless you bring your own CLI credentials, mounted workspace, and remote sandbox.

./start.sh boots the Convex + markdown quickstart path by default. Use ./start.sh convex on first run (or after ./start.sh stop) to start self-hosted Convex via Docker and print the admin key. Convex data lives in the convex_data Docker volume; the dashboard is at http://127.0.0.1:6791.

Root env files now have one canonical tracked reference: .env.example. Run bun run setup:env to create or repair the gitignored .env used by ./start.sh and bun dev.

Local development boots the agent server at http://127.0.0.1:2000. Open the admin UI at http://127.0.0.1:2000/admin. Port 5173 is an internal Vite HMR process only (proxied through :2000/admin); do not open :5173 in the browser.

Reset local state:

./start.sh reset-fresh       # wipe Convex data + .phantasy/, fresh admin/phantasy login
./start.sh reset-workspace   # remove .phantasy/ only; keeps Convex database

./start.sh restart only stops and re-bootstraps Convex — it does not wipe stored data or credentials.

Workspaces

• Character: identity, character logic, asset bindings, voice, memory, knowledge, and interaction orchestration
• Site: pages, posts, media, content APIs, publishing
• Business: channels, integrations, subscriptions, monetization
• Workflows: workflows, jobs, schedules, approvals
• Operations: providers, auth, logs, monitoring, developer tools

Trust Model

• Admin routes are protected by default.
• Developer, Test, and headless developer-tool file/task APIs are operator-only surfaces, not end-user product tabs.
• Internal compatibility routes may still use workbench; that name refers to Operations developer tooling, not a Workbench UI workspace.
• Authenticated admin users should be treated as operator-level host access when developer-tools is enabled.
• Shared/public developer-tools exposure requires a second explicit override via PHANTASY_ALLOW_SHARED_DEVELOPER_TOOLS=true.
• Runtime capabilities are explicit.
• External plugin loading is disabled by default.
• Remote plugin install is disabled by default.
• Published package contents are allowlisted.

Release Checks

npm run release:check

Docs And Guides

• Quickstart: apps/docs/src/docs/content/getting-started/quickstart.md
• Docs home: apps/docs/src/docs/content/index.md
• Why Phantasy: apps/docs/src/docs/content/getting-started/why-phantasy.md
• Character Logic: apps/docs/src/docs/content/features/character-logic.md
• Character Runtime API: apps/docs/src/docs/content/api/character-runtime.md
• Runtime map: apps/docs/src/docs/content/architecture/runtime-map.md
• Agent framework beta guide: apps/docs/src/docs/content/guides/advanced/agent-framework-beta.md
• Architecture overview: apps/docs/src/docs/content/architecture.md
• Runtime boundaries: apps/docs/src/docs/content/architecture/runtime-boundaries.md
• Proof ladder: apps/docs/src/docs/content/architecture/proof-ladder.md
• Replay-eval guide: apps/docs/src/docs/content/development/replay-eval.md
• Docs app: apps/docs/README.md
• Installation: apps/docs/src/docs/content/getting-started/installation.md
• Phantasy vs Party Quest: apps/docs/src/docs/content/architecture/phantasy-vs-party-quest.md
• Party Quest compatibility: apps/docs/src/docs/content/integrations/party-quest-compatibility.md
• Monorepo layout: apps/docs/src/docs/content/architecture/monorepo-layout.md
• Release checklist: apps/docs/src/docs/content/development/release-checklist.md
• Release notes and migration notes: apps/docs/src/docs/content/maintenance/open-source-release-notes.md
• 10-minute companion launch: apps/docs/src/docs/content/guides/quickstarts/companion-launch.md
• Starter asset packs: apps/docs/src/docs/content/guides/media/starter-asset-packs.md
• Contributor docs workflow: apps/docs/src/docs/content/development/documentation.md
• Contributing
• Open Source FAQ
• Third-Party Notices

Community

Issues, discussions, and pull requests are welcome. For larger changes, open a draft PR or discussion early so the owning workspace and architecture shape are clear before implementation spreads.

License

Dual license. Core runtime and product surfaces use FSL-1.1-Apache-2.0; templates and SDK packages use MIT. See LICENSES/README.md.

Phantasy Cloud is proprietary and lives in phantasy-bot/cloud.