Amagi is a self-hosted bookmark control plane.
It is not just a bookmark syncer. The project is designed around cloud-owned bookmark state, rule-driven projection, manual preview/apply sync, browser-specific capabilities, and private vault libraries that do not leak into ordinary browser bookmark trees by default.
Status: early prototype
amagi is not production-ready. The architecture, APIs, database schema, configuration surface, browser extension packaging, and sync protocol are still allowed to change. Do not treat the current code or docs as a stable release contract.
There is no stable packaged release yet. Use this repository as a development workspace and architecture prototype.
The intended product shape is:
- Rust + Axum API server backed by PostgreSQL
- SeaORM / SeaQuery schema and repository boundary
- SecurityDept token-set OIDC integration for browser and dashboard authentication
- Dashboard Web UI for library, sync, vault, and conflict management
- WXT-based browser extension shell with a shared WebExtension adapter
- Shared TypeScript sync client for manual preview/apply orchestration
The current implementation is a staged baseline, not a finished product. Some surfaces exist only as skeletons or thin vertical slices while the core model is still being validated.
Start with:
Local setup:
just setupStart local development dependencies, including PostgreSQL and the local Dex OIDC provider:
just dev-depsFor the Iter12 happy path, just dev and just dev-api load dev/amagi.config.local.toml by default. The local Dex demo credentials are amagi/amagi, Dashboard auth returns through http://127.0.0.1:4174/auth/token-set/oidc/source/default/callback, and devBearerToken is now only an advanced fallback for SDK debugging.
Common loops:
just dev-api
just dev-dashboard
just dev-extension-chrome
just lint
just typecheck
just test
just buildIf your non-interactive shell cannot find tools managed by mise, wrap commands for that shell only:
mise exec --command "just lint"Do not add mise exec noise to project recipes solely for agent shells.
- The cloud database is the source of truth. A browser's native bookmark tree is only a projection.
- Sync is rule-driven and explicit. The default workflow is scan, preview, user confirmation, apply, then ack.
- Normal libraries and vault libraries are separate security and sync concepts. Vault content must not be sent through ordinary browser sync streams by default.
- Protocol-bound auth endpoints use the stable
/api/auth/...facade shape; business resources use versioned/api/v1/...APIs. - Browser extension work should converge on WXT plus a shared WebExtension adapter, not long-lived per-browser adapter packages.
- Safari and mobile browsers are degraded-capability targets until their native bookmark control constraints are explicitly solved.
Source documentation lives in docs/en and docs/zh.
For implementers:
Documentation should describe current behavior or explicit future plans. Historical implementation notes belong in CHANGELOG.md or temp/IMPL_* iteration files.
- Full bidirectional sync with Safari's native bookmark tree
- Native mobile bookmark tree control
- End-to-end encrypted search
- Real-time CRDT collaboration
- Complex multi-tenant team sharing
- Stable public package or Docker release contract
These may be added later, but they should evolve from the documented source-of-truth, projection, sync, and vault model instead of reversing those foundations.
The project name amagi comes from "Amagi", a state-management maid robot from the light novel series "I'm the Villainous Lord of the Interstellar Nation!".
In this project, amagi's role is the control plane for bookmark state, sync projection, device coordination, authorization, unlock, and audit.