FAQ

Getting started

Q: What's the absolute fastest way to try ObjectOS? A: npm i -g @objectstack/cli && os start — then open http://localhost:3000. See Quickstart.

Q: Do I need Docker? A: No. Node 22+ and the CLI are enough. Docker is the recommended production deployment shape.

Q: Do I need a database? A: No, not to start — ObjectOS uses local SQLite by default. Swap for Postgres / MySQL / Turso / Mongo when you go to production.

Q: Do I need an account / cloud service? A: No. ObjectOS is fully self-contained. ObjectOS Cloud is optional for multi-environment / multi-app deployments with a control plane.

Architecture

Q: Can I use Postgres / MySQL / MongoDB? A: Yes — Postgres, MySQL, SQLite, Turso/libSQL, and MongoDB are supported drivers. See Runtime Configuration.

Q: Can I disable the UI / Account portals and use only the REST API? A: Yes. Run os start --no-ui or set the corresponding flags. The REST API is the same whether the UIs are mounted or not.

Q: Can I use my own front-end instead of the generated UI? A: Yes. The generated UI uses the same /api/v1/* endpoints you'd call from your own code. Use @objectstack/client SDK or any HTTP client.

Q: Does ObjectOS support GraphQL? A: No. REST is the API surface. The GraphQL endpoint was removed in ObjectStack 17.0 — it had never been implemented behind the route, and /graphql now returns 404. Use the generated REST API with the ObjectQL query language (over ?filter= / ?sort= / ?expand=), which covers the same ground. A third-party system that speaks GraphQL is unaffected: graphql remains a valid protocol for an external datasource, which is a client of someone else's API rather than a surface ObjectOS serves.

Q: How is multi-tenancy handled? A: One deployment serves one app, against one database — see Architecture. Several organizations can share that deployment: a walled tenancy posture (OS_TENANCY_POSTURE) puts up the per-organization isolation wall, and it is a licensed capability the runtime refuses to start without. What the wall separates is the organizations' data and memberships, not the metadata — schema is scoped to the deployment, not to an organization, which is why a walled deployment must also declare which AI agents are mounted. Isolation stronger than the wall is deployment separation: a customer that must have its own database gets its own deployment. See Multi-organization deployments.

Q: Can ObjectOS run in a serverless / Lambda environment? A: The runtime is a long-lived Node process — designed for containers or VMs, not stateless functions. The kernel is built at startup and the process reports ready only afterwards; that warm in-process state, and the Better Auth session model, are what a per-invocation function cannot keep.

Q: Does it scale horizontally? A: Yes. Run multiple instances behind a load balancer. Sessions live in the database (not in-memory), so any instance can serve any request. Use Redis for shared rate limiting and queue if you enable those capabilities.

Data & migrations

Q: How are schema migrations handled? A: The driver syncs the database schema to your declared objects on boot. For Postgres, that's CREATE TABLE / ALTER TABLE statements. For controlled migrations in regulated environments, set OS_SKIP_SCHEMA_SYNC=1 and manage DDL yourself.

Q: What happens to data when I rename a field? A: A rename is a destructive change at the data layer (it looks like "drop old column, add new column"). Use os diff to detect this and add a migration step (rename column in DB before deploying the new artifact).

Q: Can I import data from CSV / Excel / Salesforce? A: CSV: yes, via os data create in a loop or the bulk upload in the UI. Salesforce: best path today is to export to CSV and import. Native connectors are on the roadmap.

Q: Will upgrading ObjectOS lose my data? A: No. Patch and minor upgrades are non-destructive. Major upgrades (e.g. 4 → 5) document required migrations explicitly. Back up first — Backup & DR.

Permissions & multi-tenancy

Q: How do I do row-level security? A: Declare a sharing rule (declarative, like Salesforce) or a CEL predicate on an object's recordAccess config. The security plugin injects the corresponding filter on every query. See Permissions.

Q: Can I make some fields invisible to certain users? A: Yes — field-level security in permission sets. Hide or read-only, per field per permission set. Enforced uniformly across REST, ObjectQL, and the UI. See Permission Sets.

Q: How do I integrate Okta / Entra / Keycloak? A: OIDC. Configure the discovery URL + client id/secret in Setup → Authentication (or via env). Provider callback URL is /api/v1/auth/oauth2/callback/<provider-id>. See Authentication.

Integrations

Q: Can I send webhooks? A: Yes — enable webhooks in requires. ObjectOS uses a persistent outbox with HMAC-SHA256 signing. See Webhooks.

Q: Can I integrate with Zapier / Make / n8n? A: Yes — webhooks for outbound and the REST API + API keys for inbound. Native connectors for popular iPaaS tools are on the roadmap.

Q: Can AI agents call my ObjectOS? A: Yes, via MCP (@objectstack/mcp) — exposes objects (and, increasingly, actions) as MCP tools that Claude Desktop, IDEs, Claude Code, or any other MCP client can use. This is the AI path on the free, open-source ObjectStack framework (bring your own model); the in-product AI Builder / "ask your data" assistant is what the paid ObjectOS editions add. See AI Service.

Customization

Q: Can I write custom plugins? A: Yes — plugins follow a simple DI + lifecycle pattern (init → start → destroy). See @objectstack/plugin-* packages on GitHub for examples.

Q: Can I customize how ObjectOS looks? A: Branding (logo, accent color, default theme) is in Setup → System Settings. Deep UI customization means forking @objectstack/client-react or building your own front-end against the REST API.

Q: Can I add languages other than English? A: Yes — i18n is first-class. Use os i18n extract / os i18n check and ship a translation bundle.

Operations

Q: What's the recommended production deployment? A: Docker (or Kubernetes for multi-pod) + managed Postgres + S3 or R2 for files + your secret manager for OS_AUTH_SECRET. See Production Readiness.

Q: Does ObjectOS have a status page? A: For your self-hosted deployment, status is your concern — point your monitor at /api/v1/health for liveness and /api/v1/ready for readiness, the pair Docker and Kubernetes wire up. For hosted services, see status.objectstack.ai.

Q: What metrics should I monitor? A: 5xx rate, p95 latency, readiness (/api/v1/ready). There is no auth-failure metric to monitor — review sign-in activity in Setup's Auth audit view instead. Minimal Prometheus example in Observability.

Q: How do I take a backup? A: Back up the database and the storage bucket — those hold all customer data. ObjectOS itself is stateless. See Backup.

Pricing & legal

Q: Is ObjectOS free? A: ObjectOS is a commercial product (there is a free Cloud tier to start on). The free, self-hostable platform is the open-source ObjectStack framework (Apache-2.0): no seats, no usage tier, no license server — with AI over MCP (bring your own model). ObjectOS adds the embedded in-UI AI + governance and official operations, and you pay only for AI seats (viewers and non-AI users are free). See Editions.

Q: Can I use it in a commercial product I sell? A: The ObjectStack framework — yes, Apache-2.0 allows commercial use with no royalty. Redistributing ObjectOS itself requires an OEM agreement. See License & Pricing.

Q: Do you collect telemetry? A: The open-source ObjectStack runtime makes zero outbound calls unless you configure them (OIDC, email, AI, webhooks). Self-managed ObjectOS additionally validates its license online (air-gapped Enterprise licenses are offline-validated). See Security & Compliance.

Q: Is ObjectOS SOC 2 / ISO 27001 / HIPAA / GDPR compliant? A: ObjectOS provides the primitives every framework requires (RBAC, audit, encryption-ready, residency). Certification is a property of your deployment, not the binary. Many ObjectOS deployments are certified. See Security & Compliance.

Getting unstuck

Q: Something's broken — where do I start? A: os doctor. It catches 80% of misconfigurations on its own. After that, Troubleshooting.

Q: Where do I report a bug? A: GitHub Issues. Include os doctor output. Security issues: security@objectstack.ai.

Q: Where do I get help from humans? A: GitHub Discussions, the community Discord, or sales@objectstack.ai for commercial support.