Extra Tools & Swappable Capabilities

In MicroCoreOS, the base install provides the essential microkernel, default SQLite database, HTTP gateway, in-process event bus, and logging. Everything else is an Extra: optional infrastructure that can be installed on demand with zero manual wiring.

uv run microcoreos add <extra>

microcoreos add performs three acts automatically:

1. Installs the dependency via uv add 'microcoreos[extra]'
2. Moves the source code from extras/available_* into your active tools/ and domains/
3. Appends the required configuration keys into your .env (never overwriting existing values)

---

1. auth — Authentication & Session Management

Installs tools/auth and domains/users with complete registration, login, JWT issuance, identity inspection, and logout.

uv run microcoreos add auth

Methods (self.auth)

• hash_password(password: str) -> str: Hashes password using bcrypt.
• verify_password(plain: str, hashed: str) -> bool: Verifies password against hash.
• create_token(data: dict, expires_delta: timedelta | None = None) -> str: Issues signed JWT token.
• decode_token(token: str) -> dict: Decodes token or raises exception on invalid signature/expiry.
• validate_token(token: str) -> dict | None: Validates token, returns claims dict or None on failure (used directly as auth_validator in HTTP routes).

Environment Variables

Variable	Default	Description
AUTH_SECRET_KEY	(required)	Secret string for HMAC-SHA256 signing
AUTH_ALGORITHM	HS256	JWT algorithm
AUTH_TOKEN_EXPIRE_MINUTES	60	Token expiration time in minutes

---

2. postgres — PostgreSQL Database Tool

Drop-in replacement for tools/sqlite with exact contract parity: query, query_one, execute, execute_many, and nested transaction support via asyncpg.

uv run microcoreos add postgres

Contract Parity

PostgreSQL and SQLite share the exact same parameter placeholder convention: $1, $2, $3.... Swapping SQLite for PostgreSQL requires zero changes to plugin queries.

Environment Variables

Variable	Default	Description
PG_HOST	localhost	PostgreSQL server host
PG_PORT	5432	PostgreSQL server port
PG_USER	postgres	Database username
PG_PASSWORD	postgres	Database password
PG_DATABASE	microcoreos	Target database name
PG_MIN_CONNS	5	Minimum connection pool size
PG_MAX_CONNS	20	Maximum connection pool size

---

3. redis — Redis State & Redis Streams Event Bus

Installs tools/redis_state (replacing the default in-memory state dictionary with a distributed Redis cache) and adds the Redis Streams event bus driver.

uv run microcoreos add redis

Capabilities

• Distributed State Cache: Key-value storage with TTL support (set, get, delete, exists, expire).
• Distributed Event Bus: Setting EVENT_BUS_DRIVER=redis_streams in .env upgrades the event bus to persistent Redis Streams with consumer groups and at-least-once delivery across multiple replicas.

Environment Variables

Variable	Default	Description
REDIS_URL	redis://localhost:6379/0	Connection URL (or use separate host/port)
REDIS_HOST	localhost	Redis host
REDIS_PORT	6379	Redis port
REDIS_PASSWORD	""	Redis authentication password
REDIS_DB	0	Redis logical database number

---

4. s3 — Object Storage Tool

Installs tools/s3 for interacting with AWS S3, Cloudflare R2, MinIO, or any S3-compatible storage backend via aioboto3.

uv run microcoreos add s3

Methods (self.s3)

• upload_file(key: str, data: bytes, content_type: str = "application/octet-stream") -> str
• download_file(key: str) -> bytes
• delete_file(key: str) -> bool
• generate_presigned_url(key: str, expires_in: int = 3600, method: str = "get_object") -> str

Environment Variables

Variable	Default	Description
S3_BUCKET	(required)	Target S3 bucket name
AWS_ACCESS_KEY_ID	(required)	AWS / S3 access key
AWS_SECRET_ACCESS_KEY	(required)	AWS / S3 secret key
AWS_REGION	us-east-1	AWS region
S3_ENDPOINT_URL	""	Custom endpoint (e.g. http://localhost:9000 for MinIO)

---

5. scheduler — Cron & Durable One-Shots

Installs tools/scheduler powered by APScheduler and the domains/scheduler domain for durable distributed one-shot jobs.

uv run microcoreos add scheduler

Architecture

• Beat vs Worker: In multi-replica deployments, set SCHEDULER_ENABLED=true on exactly one instance (the beat leader) and false on workers.
• Event-Driven Delivery: Jobs publish events to the event bus; consumer group workers execute the handler with automatic fleet-wide load balancing.
• Durable One-Shots: Schedule future events via bus.request("scheduler.one_shot.schedule", {"run_at": timestamp, "event": "...", "payload": {...}}).

Methods (self.scheduler)

• add_job(callback, trigger="cron", id=None, **trigger_args)
• add_one_shot(callback, run_at: datetime, id=None)
• remove_job(job_id: str)

---

6. kafka — Enterprise Kafka Event Bus

Drops kafka_driver.py into tools/event_bus/ and sets EVENT_BUS_DRIVER=kafka.

uv run microcoreos add kafka

Environment Variables

Variable	Default	Description
KAFKA_BOOTSTRAP_SERVERS	localhost:9092	Comma-separated broker addresses
KAFKA_GROUP_ID	microcoreos	Consumer group prefix

---

7. rabbitmq — RabbitMQ AMQP Event Bus

Drops rabbitmq_driver.py into tools/event_bus/ and sets EVENT_BUS_DRIVER=rabbitmq.

uv run microcoreos add rabbitmq

Environment Variables

Variable	Default	Description
RABBITMQ_URL	amqp://guest:guest@localhost:5672/	AMQP connection URL

---

8. chaos — Chaos Engineering & Fault Simulation

Installs tools/chaos and domains/chaos for chaos testing and verifying ToolProxy failover.

uv run microcoreos add chaos

• CHAOS_ENABLED=true|false: When enabled, intentionally triggers transient faults and latency injections during boot and execution.
• Strictly for local testing: Never activate in production.

---

9. ping — Minimal Reference Domain

Installs domains/ping providing a single GET /ping route. Used as a minimal syntax reference when creating your first plugins.

uv run microcoreos add ping