A modular personal platform.
기록, 서비스, 도구와 외부 시스템을 하나의 환경으로 조립하는 개인용 모듈형 플랫폼입니다.
Important
Pre-alpha / Design and v0 Implementation Stage Manafield는 현재 Core architecture와 Module Protocol을 설계하고 있는 초기 단계입니다.
한국어 문서를 기준 문서로 우선합니다.
한국어판과 영문판의 내용이 다를 경우 한국어판을 우선합니다.
Manafield는 여러 프로그램과 서비스를 하나의 방식으로 연결하고 관리하는 개인용 모듈형 플랫폼입니다.
핵심 원칙은 간단합니다.
Core는 엄격하게, Module은 자유롭게.
Manafield Core는 Rust로 작고 엄격하게 만들고, Module은 Python, Go, Node.js, Java, Rust 등 어떤 언어든 상관없이 API 계약만 지키면 연결할 수 있는 구조를 목표로 합니다.
Module이 외부에 제공하는 호출 가능한 기능은 Operation이라는 공통 계약으로 표현합니다. Operation은 기능 ID, optional description, Input/Output Schema, 호출 방식(Binding), Payload 형식(Codec)을 설명하며, Core는 이를 통해 Module의 구현 언어를 몰라도 어떤 기능을 어떻게 호출할 수 있는지 이해합니다.
Module 간 의존성과 Database/Cache/Storage 같은 기반 자원 요구는 모두 Capability Contract로 표현합니다. Fork나 대체 구현, Provider가 관리하는 Resource도 같은 versioned Capability matching에 참여할 수 있습니다.
flowchart TB
Web["Manafield Web<br/>(Optional)"]
Core["Manafield Core<br/>Rust<br/><br/>Registry · Lifecycle · Runtime · Health<br/>Permission · Settings · Discovery · Event"]
Module["Module<br/>Python"]
Service["Service<br/>Node.js"]
Integration["Integration<br/>Go"]
Web -->|"Core API"| Core
Core -->|"Module Protocol"| Module
Core -->|"Module Protocol"| Service
Core -->|"Module Protocol"| Integration
개인 홈페이지에 기능 하나를 추가할 때마다 전체 프로젝트를 뜯어고치는 대신,
- 필요한 기능만 골라 붙이고
- 독립 서비스도 같은 방식으로 관리하고
- Web UI가 없어도 동작하며
- 필요하면 Web, CLI, Mobile 같은 다른 View를 붙이고
- 장기적으로는 Module Package를 설치하는 것만으로 기능을 추가하는
그런 플랫폼을 직접 만드는 것이 목표입니다.
manafield.studio는 Manafield 자체가 아니라 Eventide가 운영 중인 하나의 초기 Manafield 인스턴스입니다. 현재 동작하는 v0 구성과 장기 Runtime/Module 관리 목표는 구별합니다.
현재 Manafield Core 개발 기준 Rust toolchain은 Rust 1.99.0입니다.
rustc 1.99.0cargo 1.99.0- 루트의
rust-toolchain.toml로 개발 Toolchain을 고정합니다.
rustup을 사용하는 환경에서는 이 Repository 안에서 cargo 또는 rustc를 실행할 때 지정된 Rust 1.99.0 Toolchain이 자동으로 선택됩니다.
이 버전은 현재 개발 기준이며, 아직 공식적인 MSRV(Minimum Supported Rust Version) 를 의미하지는 않습니다.
Core는 (warn)[source] 메시지 형식의 기본 콘솔 로그를 남기며, 공식 Docker 배포에서는 별도의 영구 볼륨에 구조화된 JSONL을 기록합니다. 운영자는 docker exec manafield-core-1 /usr/local/bin/manafield log --level warn 같은 방식으로 필터링할 수 있습니다.
선택적 PostgreSQL 로그 Mirror는 core.bindings.loggingState에 PostgreSQL Resource를 지정하면 Jenkins에서 전용 DB Role/Schema가 자동 할당됩니다. Account 로그인 감사 이력은 별도 DB에 저장되어 Manage에서 log.audit.read 확인 후 열람 가능하지만, Core JSONL/DB 로그의 인증된 Role 기반 웹 뷰어는 다음 통합 작업입니다. Logging 설계 및 현재 지원 범위를 참고하세요.
Manafield는 별도 실행파일인 manafield CLI와 manafield-core 서버를 같은 배포 묶음으로 제공합니다. CLI는 상태 조회와 Instance 작업을 담당하고, Core 서버는 API/Registry를 담당합니다.
manafield health
manafield ps
manafield resource
manafield resource manafield-postgres
manafield plan instance.yaml --output build-plan.json --ci-output ci-plan
manafield build all
manafield build all --no-docker --output ./dist/test
manafield build "$WORKSPACE" "$CORE_SHA" "$CORE_IMAGE"
manafield deploy /opt/manafield/instance/releases/123health, ps, resource 같은 운영 command는 Core API를 사용합니다. 기본 API 주소는 http://127.0.0.1:8080이며, 필요하면 MANAFIELD_CORE_URL로 변경할 수 있습니다.
plan은 Instance Definition을 검증하고 Build Plan으로 해석합니다. deploy RELEASE_DIR은 이미 staging된 release에 대해 Docker Compose를 실행합니다. build all은 외부 Module을 제외한 Manafield 플랫폼 자체의 실행파일과 Docker 이미지(Core 및 공식 PostgreSQL Provider)를 생성합니다. --no-docker는 바이너리만 빌드합니다. 기존 build WORKSPACE REVISION CORE_IMAGE는 Jenkins 호환 과도기 명령입니다. verify / rebuild와 source checkout, release 준비 기능은 아직 Jenkins에서 CLI로 옮기는 중입니다. 지원되는 v0 범위의 Instance는 CLI + Docker로 직접 구축할 수 있습니다. 다만 공개 Ingress, 다중·외부 Resource, 배포 전체 Health 검증·복구는 기존 Jenkins 경로나 후속 작업이 필요합니다.
Core 서버는 manafield-core로 실행합니다. manafield를 인자 없이 실행하면 CLI 도움말을 출력하며, 이전의 manafield serve는 더 이상 서버를 시작하지 않습니다.
Manafield v0의 전체 Instance 구축과 배포에는 Docker가 필요합니다. Docker는 v0에서 의도적으로 채택한 deployment substrate이며, Jenkins는 필수 구성요소가 아닙니다.
현재 CLI는 제한된 v0 Instance를 deploy [release-id] --source DIR로 직접 준비·배포할 수 있습니다. 준비된 산출물을 적용하는 레거시 deploy RELEASE_DIR과는 구별해야 하며, 직접 배포에도 Docker CLI/Compose/daemon 접근이 필요합니다. Jenkins는 webhook, approval, credential integration, build history를 담당하면서 같은 CLI 경로를 호출하는 방향으로 발전합니다.
Core의 일반 Registry / Protocol 모델은 계속 Docker-specific privilege와 분리합니다. 자세한 결정은 ADR-0013을 참고합니다.
구현된 build all은 Manafield 플랫폼 자체만 빌드합니다. 이미 존재하는 Module/Resource를 매번 빌드하는 명령이 아닙니다. Instance의 연결과 배포는 별도로 취급합니다.
manafield use A
manafield module bind echo-prod state main-postgres
manafield deploy B
A의 불변 YAML을 temp로 불러와 Requirement Binding만 변경하고, 새 ID B의 불변 YAML로 저장해 배포하는 방식입니다. 기본 ID는 vN_YYYYMMDDTHHMMSSZ(UTC), 저장 위치는 manafield/release/<id>.yaml입니다. 기존 PostgreSQL 데이터와 영속 Volume은 Release 간에 유지합니다.
use, module bind, 불변 Release 저장 및 사전 준비된 산출물의 Release ID 배포까지 구현됐습니다. 지원되는 v0 구성은 YAML에서 Docker 이미지와 Compose 배포 산출물을 직접 생성합니다. Ingress 및 미지원 Provider는 아직 별도 경로가 필요합니다. 현재 Jenkins 호환 build WORKSPACE ...와 deploy RELEASE_DIR는 다른 동작을 합니다. ADR-0014 · CLI 가이드
새 Release CLI 사용 예시(지원되는 구성은 Docker 산출물도 직접 생성):
manafield deploy --snapshot-only --instance-root /path/to/instance
manafield deploy v1_20261008T080000Z --instance-root /path/to/instance --source /path/to/manafield-sourcedeploy <release-id>는 해당 YAML과 준비된 Build Plan의 일치 여부를 검사하며, --staged-dir가 없으면 --source의 Core 소스로 이미지를 빌드하고 Compose 산출물을 생성한 뒤 Docker 적용을 시도합니다. 자세한 제약은 CLI 가이드에서 설명합니다.
- Headless Core — Web UI가 없어도 동작합니다.
- Language-independent Modules — 언어와 Framework에 종속되지 않습니다.
- API-first Protocol — Core와 Module은 API 계약으로 연결됩니다.
- Runtime Provider — Module 실행 환경은 Core와 분리된 Provider가 담당합니다.
- Capability-based dependencies — Module identity와 기능 호환성 계약을 분리합니다.
- Resource Providers — PostgreSQL 같은 공용 기반 자원을 Module과 분리해 공급할 수 있도록 설계합니다.
- Docker-required v0 deployment — 전체 v0 Instance 구축/배포는 Docker를 요구하되 Core의 일반 모델과 Docker-specific privilege는 분리합니다.
- Optional Web Views — Module이 필요할 때만 Web UI를 제공합니다.
- Isolated Modules — Core 프로세스와 Module 실행환경을 분리합니다.
- Privilege boundary — Docker 같은 강한 권한은 Core가 아니라 별도 Runtime Provider 프로세스에 둡니다.
- Runtime abstraction — 장기적으로 Process, Remote, Kubernetes 같은 다른 Provider를 추가할 수 있도록 설계합니다.
Misskey처럼 자체 Web, DB, Cache, Storage와 Lifecycle을 가진 서비스를 Manafield가 설치하고 관리할 수 있다면, Module Host로서의 구조가 제대로 동작한다고 볼 수 있습니다.
flowchart TB
Manafield["Manafield Core"]
Docker["Docker Runtime"]
Misskey["Misskey Service Module"]
App["Application"]
Postgres["PostgreSQL"]
Redis["Redis"]
Storage["Storage"]
Manafield --> Docker
Docker --> Misskey
Misskey --> App
Misskey --> Postgres
Misskey --> Redis
Misskey --> Storage
Manafield 본체와 별도로 개발·배포되는 공개 모듈 및 모듈 제품군입니다. 실제 Instance에서는 필요한 모듈만 선택해 설치할 수 있으며, 모듈 버전과 배포 주기는 Core와 독립적입니다.
- Manafield Web — 선택적으로 설치하는 공식 Web Shell.
- Manafield Manage — 모듈·리소스 상태를 관측하는 관리 웹 모듈 제품군. Lifecycle / Monitor 등은 향후 확장 예정입니다.
개발·검증용 레거시:
- Manafield Module Reference — Module Protocol 검증용 예제. 실제 공개 모듈로 검증 범위가 대체되면 장기적으로 철거할 예정이며, 지금은 유지합니다.
각 모듈의 구체적인 설치 방법과 구현 상태는 해당 저장소의 README를 참고합니다. 이 목록에는 비공개 모듈 저장소를 포함하지 않습니다.
2026-10-10 구현 상태는 Roadmap과 CLI 가이드를 기준으로 확인하세요. 구현과 별개의 장기 설계 목표는 ADR에 기록합니다.
한국어 문서를 기준으로 유지하며, 영어 문서는 이를 바탕으로 동기화합니다.
- CLI / Docker v0 실행 가이드
- Architecture
- Module Protocol
- Operation
- Capability Contract
- Web Surface
- Official Web Shell
- Roadmap
- Architecture Decision Records
수정·재배포할 때는 원본의 라이선스와 attribution을 유지하고, 수정된 파일에는 변경 사실을 명시해야 합니다. 자세한 내용은 NOTICE를 참고해 주세요.
The Korean documentation is the primary source of truth.
If the Korean and English versions differ, the Korean version takes precedence.
Manafield is a modular personal platform for composing independent services, tools, modules, and integrations into one environment.
Its guiding principle is:
Strict Core, free Modules.
The Core is implemented in Rust, while Modules may use any language or framework as long as they implement the Manafield Module Protocol.
Callable functionality exposed by a Module is described through a common Operation contract. An Operation describes its ID, optional description, Input/Output Schema, invocation Binding, and Payload Codec so Core can understand what a Module provides without knowing its implementation language.
Dependencies and infrastructure needs such as databases, caches, and storage are all expressed through Capability Contracts. Compatible forks, alternate Module implementations, and Provider-managed Resources can participate in the same versioned matching model.
The current Manafield Core development baseline is Rust 1.99.0.
rustc 1.99.0cargo 1.99.0- The repository root contains
rust-toolchain.tomlto pin the development toolchain.
When using rustup, running cargo or rustc inside this repository automatically selects the pinned Rust 1.99.0 toolchain.
This is the current development baseline and does not yet define an official MSRV (Minimum Supported Rust Version).
The distribution now ships separate manafield CLI and manafield-core server executables. The CLI performs operational queries and Instance tasks; the Core server owns the API/Registry.
manafield health
manafield ps
manafield resource
manafield resource manafield-postgres
manafield plan instance.yaml --output build-plan.json --ci-output ci-plan
manafield build all
manafield build all --no-docker --output ./dist/test
manafield build "$WORKSPACE" "$CORE_SHA" "$CORE_IMAGE"
manafield deploy /opt/manafield/instance/releases/123Operational commands such as health, ps, and resource use the Core API. The default API address is http://127.0.0.1:8080 and may be overridden with MANAFIELD_CORE_URL.
plan resolves an Instance Definition locally. deploy RELEASE_DIR runs Docker Compose for a previously staged release. build all creates a Manafield-only platform bundle (CLI, Core, official tools) and Docker images for Core / the official PostgreSQL Provider; --no-docker builds binaries only. Legacy build WORKSPACE REVISION CORE_IMAGE remains Jenkins-specific. Verify, rebuild, source checkout, and release staging are still migrating; the CLI already builds supported v0 Instances from scratch, while public ingress, multiple/external Resources, full health verification, and rollback remain future work.
Run manafield-core to start the Core server. Running manafield without arguments prints CLI help; manafield serve does not start the Core server.
A full Manafield v0 Instance build and deployment requires Docker. Docker is an intentional v0 deployment substrate; Jenkins is not required.
CLI + Docker already supports a bounded direct deployment profile through deploy [release-id] --source DIR; it builds/stages its own artifacts. The legacy deploy RELEASE_DIR still requires pre-staged artifacts. Both paths need Docker CLI/Compose/daemon access. Jenkins provides webhooks, approvals, credential integration, and build history.
The general Core registry/protocol model remains separated from Docker-specific privilege. See ADR-0013.
The implemented build all builds only the Manafield platform, not all already-published Modules/Resources. Editing Instance Bindings and deploying Releases are separate concerns.
manafield use A
manafield module bind echo-prod state main-postgres
manafield deploy B
Load immutable YAML A as a temp working copy, edit Requirement Bindings, then snapshot it as new immutable B and apply it. Default IDs follow vN_YYYYMMDDTHHMMSSZ (UTC) and are stored at manafield/release/<id>.yaml. Reuse persistent PostgreSQL data and volumes across Releases.
use, module bind, immutable Release snapshots and staged-artifact Release-ID deployment are implemented. Supported v0 configurations are now prepared from YAML, including Module images and Compose artifacts, while Ingress and unsupported Resources remain separate. The Jenkins-compatible build WORKSPACE ... and deploy RELEASE_DIR commands have different semantics. ADR-0014 · CLI guide
- Headless Core — no mandatory Web UI
- Language-independent Modules
- API-first Module Protocol
- Runtime Providers separated from Core
- Capability-based dependencies separated from concrete Module identity
- Resource Providers for shared infrastructure such as PostgreSQL
- Docker-required v0 deployment, while keeping Docker-specific privilege outside the general Core model
- Optional Web Contributions
- Isolated Module execution
- Privilege boundaries for powerful runtime control
- Runtime abstraction for future Process, Remote, and Kubernetes Providers
manafield.studio is not Manafield itself. It is currently an early Manafield instance operated by Eventide. Implemented v0 behavior is distinct from the longer-term lifecycle/runtime goals.
A major milestone is to:
Run and manage Misskey as a Manafield Service Module.
This will validate real-world lifecycle management involving an application runtime, database, cache, storage, networking, health checks, and a Web service.
Public modules and module families are developed and released independently from Manafield Core. An Instance installs only the modules it needs.
- Manafield Web — optional official Web Shell.
- Manafield Manage — administrative observation modules. Lifecycle and monitoring extensions are planned, not yet implemented.
Legacy / testing:
- Manafield Module Reference — Module Protocol reference module. Retained for now, planned to be retired once real public modules cover its verification purpose.
See each repository's README for current features and installation details. Private module repositories are not listed here.
For implementation status as of 2026-10-10, see the Roadmap and CLI guide. ADRs also preserve earlier architecture decisions.
- CLI / Docker v0 execution guide
- Architecture
- Module Protocol
- Operation
- Capability Contract
- Web Surface
- Official Web Shell
- Roadmap
- Architecture Decision Records
Pre-alpha / Design and v0 Implementation Stage
The architecture and protocol are still evolving.