# Devias > Documentation for Devias, an open-source platform that works as an operating system for a business: records, workflows, agents and permissions in a core, with installable modules. > ## Agent Instructions > The docs are served at https://docs.devias.io. Every path in these docs is relative to that root: /llms.txt is https://docs.devias.io/llms.txt. > Devias is an open-source platform that works as an operating system for a business: a core (records, views, workflows, agents, permissions) with installable modules. > Pages are typed by folder. concepts/ explains what things are, guides/ gives procedures, reference/ is exhaustive (SDK, CLI, HTTP API), operate/ covers hosting. Use /start/glossary for exact terms. > Every id in a module (module, object, field, view, action, workflow, step, connection, variable, event, policy) is a uuid. Generate them with `devias id `. Never invent dotted or readable ids. > Run `devias plan` and read its output before `devias apply`. Apply only what the plan says. > The OpenAPI document, including the routes of the modules in the reference setup, is at /reference/api/openapi.json. > Devias is young and changes quickly. If a page and the source repository (github.com/devias-io/devias) disagree, the repository is right. - [What Devias is](https://docs.devias.io/index.md): Devias is an open-source platform that works as an operating system for a business. A core provides records, workflows, agents and permissions, installable modules add areas such as CRM and invoicing, and it runs on your own server. - [Quickstart](https://docs.devias.io/quickstart.md): Procedure to run Devias on one machine with Node.js 22, pnpm 10 and the embedded database. Starts the API on port 3000 and the studio on 5173, creates a workspace, installs the CRM module from a reviewed plan and turns on agents. Each step states its expected result. - [Use these docs with AI](https://docs.devias.io/start/use-with-ai.md): How an AI agent reads Devias documentation and acts on Devias. Machine-readable entry points (llms.txt, llms-full.txt, Markdown pages, MCP server, skill.md, OpenAPI), how pages are organised, rules for changing a workspace, and which page answers which task. - [Glossary](https://docs.devias.io/start/glossary.md): Definitions of every Devias term, with the page that explains it. Includes the rule for name, label and title, what an id is, every term from action to workspace, and a table mapping each define function of a module manifest or studio config to the page that documents it. - [Architecture](https://docs.devias.io/concepts/architecture.md): The three parts of Devias and how a change travels through them. The studio is the React app, the server is an API with a data engine over Postgres, and modules plug into both. Every client uses the same API and the same permission check. - [Data model](https://docs.devias.io/concepts/data-model.md): How Devias stores business data. A workspace holds objects, an object has fields, and the rows of an object are records. Lists every built-in field type by API name with what it can do, how relations work, and who owns objects and fields. - [Views, layouts and navigation](https://docs.devias.io/concepts/views-and-layouts.md): How records are listed and shown. A view is a saved table, kanban or calendar of one object, a layout arranges one record's page from blocks in a tabs, column or split shape, and navigation items and commands let people reach them. - [Modules](https://docs.devias.io/concepts/modules.md): What a Devias module is, which modules are core, how installing works with a plan you review before applying, and how ids keep a module's data separate from a workspace's own data. - [Workflows and tasks](https://docs.devias.io/concepts/automation.md): How work is automated and tracked in Devias. A workflow is a trigger and steps that run in order as the workflow itself. Lists the five trigger kinds, the two step kinds, run states and limits, then tasks, documents and notifications. - [Agents](https://docs.devias.io/concepts/agents.md): What a Devias agent is and how it behaves. An agent is instructions plus a list of tools, acts with the role of the person who asked, and stops at an approval card for any tool set to ask first. Covers where agents come from, skills and the provider key agents need. - [Access and permissions](https://docs.devias.io/concepts/access.md): Who can do what in Devias. Every request from a person, API key, workflow, module or agent passes the same permission check in the server. Lists the three member roles, what an API key can do, and how workflows, modules and agents are limited. - [Navigate the studio](https://docs.devias.io/guides/studio/navigate-the-studio.md): Where everything is in the Devias studio. Lists the regions of the window (sidebar, search bar, assistant, bell, settings), what Home shows, the command palette, and every keyboard shortcut. - [Records and views](https://docs.devias.io/guides/studio/records.md): How to work with records in the studio. Covers the toolbar of a view (views, search, filters, sort, fields, group by, import, create), editing in place, the row menu, table, board and calendar views, creating a view, and the record page with its Actions menu. - [Import records](https://docs.devias.io/guides/studio/import.md): How to import records into any object from a CSV file in the studio. A wizard reads the file, maps columns to fields and rehearses the whole import before anything is written. Covers existing rows, the 10 MB and 50,000-row limit, and why imports do not start workflows. - [Documents](https://docs.devias.io/guides/studio/documents.md): How to write and discuss documents in the studio. A document is a page of rich text for what does not fit in a field. Covers creating one, the slash menu, @mentions of records, documents and tasks, comments on a passage, the timeline, and where documents show up. - [Tasks](https://docs.devias.io/guides/studio/tasks.md): How to track work in the studio. A task is a unit of work for a person or an agent, with a status, priority, assignee and due date. Covers the list and board views, the saved shortcuts, every task property with its allowed values, and giving a task to an agent. - [Workflows in the studio](https://docs.devias.io/guides/studio/workflows.md): How to build and run a workflow in the studio without code. Covers the five triggers and their API kinds, step types, schedules in UTC, run and step statuses, retrying a failed run, running one on a record, workflows that ship with a module, and the no-self-triggering rule. - [Use the assistant](https://docs.devias.io/guides/studio/agents.md): How to use agents in the studio. Covers opening the assistant, what to ask, how an approval card works, and where agents and skills are managed. Agents need an AI provider key and act with the role of the person who asked. - [Install and connect modules](https://docs.devias.io/guides/studio/modules.md): How to manage modules under Settings → Modules. Covers installing a module from a reviewed plan, updating and uninstalling, workspace and personal connections to outside services, and the Events and Workflows tabs of a module that receives events. - [Settings](https://docs.devias.io/guides/studio/settings.md): What each page under Settings does in the Devias studio. Lists every Settings page by group (Account, Workspace, Data, Developer), and explains inviting members and roles, shaping the data model, and creating and revoking API keys. - [What a module is](https://docs.devias.io/guides/modules/what-a-module-is.md): A Devias module is an npm package that adds one area of the business. Lists the three parts (manifest, server code, studio code), the package layout and exports, which part is required, and how a module reaches a workspace. - [Create a first module](https://docs.devias.io/guides/modules/first-module.md): A complete procedure to build a manifest-only Projects module: the package.json, ids from devias id, the manifest with one object, a table view and a sidebar item, registering it in devias.config.ts, installing it, and the expected result. - [Objects and fields in a module](https://docs.devias.io/guides/modules/objects-and-fields.md): How a module declares objects and fields. Lists every property of defineObject and defineField, the built-in field types, how to declare a relation with its inverse label, and how to add fields to an object owned by another module. - [Views and navigation in a module](https://docs.devias.io/guides/modules/views-layouts-navigation.md): How a module declares how records are shown. Lists every property of defineView (table, kanban, calendar), defineLayout with its tabs, column and split shells, the four sidebar target kinds, and defineCommandItem for the command palette. - [Actions and server code](https://docs.devias.io/guides/modules/actions-and-server-code.md): How a module declares an action once and implements it in server code. The action is then available as a record-page button, a workflow step, an agent tool and an API route. Lists input types, the handler context (ctx), and how errors and retryable errors behave. - [Connections and events in a module](https://docs.devias.io/guides/modules/connections-and-events.md): How a module connects to an outside service. Covers defineConnection (api_key and oauth2, workspace or personal), connection tests, defineVariable settings, and defineEvent with a webhook parse function that verifies signatures and returns events deduplicated by externalId. - [Workflows in a module](https://docs.devias.io/guides/modules/workflows.md): How a module ships a workflow with defineWorkflow. Covers the five triggers, what a workspace can change on a shipped workflow, making an action safe to repeat with ctx.step, RetryableError with its backoff (30 seconds doubling to one hour, at most five retries), and runtime limits. - [Agents and skills in a module](https://docs.devias.io/guides/modules/agents-and-skills.md): How a module ships agents and skills. Lists every property of defineAgent and defineSkill, what the tool list (actionIds) allows, the tools a module agent never gets, and how agents and skills are installed, updated and archived with the module. - [Plan and apply](https://docs.devias.io/guides/modules/plan-and-apply.md): How installing or updating a module works in two steps. A plan marks each item create, update, delete or conflict, and destructive changes need explicit permission. Covers the studio flow, the devias plan and apply commands with their flags and exit codes, and the API key permission needed. - [Publish a module](https://docs.devias.io/guides/modules/publishing.md): How to prepare a Devias module for sharing. Lists the identity properties (label, description, icon, logo limits, website), semantic versioning and engines, the package exports (manifest, server, studio), the experimental policy declaration, and a pre-release checklist. - [Built-in modules](https://docs.devias.io/guides/modules/built-in-modules.md): The modules in the Devias repository under modules/. A table lists what each adds, which modules it needs, and what it is a good example of (smallest module, layouts and agents, custom screens, connections, webhooks and workflows, actions on another module's records). - [Customize the studio](https://docs.devias.io/guides/customize-studio/what-you-can-customize.md): The Devias studio is a React app configured in apps/studio/src/studio.config.tsx with defineStudio. Lists every setting (title, modules, structure, defaultPage, contact, agentImages) and the kinds of parts that can be added: sidebar structure, field and view types, blocks, pages, commands and theme. - [Sidebar structure](https://docs.devias.io/guides/customize-studio/structure.md): How to arrange the studio sidebar with the structure setting of defineStudio. Lists every piece of the S builder (list, listItem, divider, objectList, view, page, navItems, objects, favorites), how objects, pages and views are named, and why S.navItems() must stay. - [Field and view types](https://docs.devias.io/guides/customize-studio/field-and-view-types.md): How a module adds a new field type or view type from its ./studio export. Lists the parts of defineFieldType (type, label, icon, cell, editor, toText, filter, sortable, groupable) and defineViewType with its capabilities, and when to use a built-in instead. - [Blocks](https://docs.devias.io/guides/customize-studio/blocks.md): How a module adds a block, a React component that Devias places on a screen. Lists the five surfaces (home, record, dialog, panel, approval), the defineBlockComponent properties, why a block is also declared in the manifest with defineBlock, and the requires property. - [Pages and commands](https://docs.devias.io/guides/customize-studio/pages-commands.md): How a module adds full screens with definePageComponent, command palette entries with defineCommand, Settings sections with defineSettingsSection, and reads studio data with hooks such as useWorkspace, useSchema, useRecords and useRecord. - [Theming](https://docs.devias.io/guides/customize-studio/theming.md): How to change the look of the Devias studio by redefining CSS variables from @devias/ui after importing its styles. Lists each variable group, how dark mode values work, the per-person light, dark or system choice, and the @source line needed for Tailwind classes in a module. - [Tools and approvals](https://docs.devias.io/guides/agents/tools-and-approvals.md): How an agent's tools and approval modes work. Lists the thirteen areas of tools, the two modes (Runs freely and Ask first), which tools ask first by default, which sensitive tools are locked to always ask, and how the approval card behaves. - [Define an agent](https://docs.devias.io/guides/agents/define-an-agent.md): How to create an agent. In the studio, start from a template (Blank, Read-only analyst or General) and set name, instructions, tools, starter prompts, Takes tasks and Default agent. In a module, declare it with defineAgent. Includes rules for writing instructions. - [Skills](https://docs.devias.io/guides/agents/skills.md): How to write and use skills. A skill is a procedure written once, with a label, a one-line description the agent matches against, and a Markdown body. Explains why a skill is not an instruction, who can use a skill, and how module skills behave. - [Deploy](https://docs.devias.io/operate/deploy.md): How to host Devias. Lists the requirements (Node.js 22, pnpm 10, Postgres 18, two secrets), the four deployment steps with the minimum environment, and requirements for secrets, addresses, a same-origin setup, live-update proxying and Sign in with Google. - [Database](https://docs.devias.io/operate/database.md): How Devias stores data. Compares the embedded PGlite database (the default when DATABASE_URL is unset) with PostgreSQL 18, shows the local Docker Compose Postgres on port 5433, and explains migrations, MIGRATE_ON_BOOT and pnpm db:migrate. - [Environment variables](https://docs.devias.io/operate/environment.md): Reference for every environment variable the Devias server and studio build read: server address and secrets, database, Google sign-in, agent provider keys and limits (AI_PROVIDER, AI_MODEL, AI_EFFORT and more), and the VITE_ build variables. Each with its default. - [Contributing](https://docs.devias.io/operate/contributing.md): The layout of the Devias monorepo (packages, apps and modules), the everyday pnpm commands, what to run after changing the database or the API (including regenerating OpenAPI and the SDK types), the smoke tests, and the licences. - [TypeScript SDK](https://docs.devias.io/reference/sdk/client.md): @devias/sdk is the typed TypeScript client the studio uses. How to create a client (baseUrl, workspaceId, apiKey), the areas it offers (records, metadata, modules, workflows, tasks, documents, comments, activity, notifications, events, ai) and how errors are thrown as DeviasApiError. - [SDK records and queries](https://docs.devias.io/reference/sdk/records-and-queries.md): How to read and write records with the TypeScript SDK. Covers records.create, get, update, delete, upsert and import, the q() query builder with select, where, orderBy, limit, cursor, include, search and count, every filter helper, cursor paging, lookup and aggregate. - [SDK metadata and modules](https://docs.devias.io/reference/sdk/metadata-and-modules.md): How to read a workspace schema with metadata.getSchema, change objects, fields, views, layouts, navigation and commands with list, get, create, update and delete, and plan, apply, uninstall and run actions of modules with the TypeScript SDK. - [SDK events and notifications](https://docs.devias.io/reference/sdk/events-and-notifications.md): How to follow workspace changes with client.events.subscribe (event type, sequence, actor and occurredAt, resuming with after, connection status) and how to send and read notifications with client.notifications, including the to targets all, roles, users and me. - [SDK mock backend](https://docs.devias.io/reference/sdk/mock-and-testing.md): How to use createMockClient from @devias/sdk/mock, a complete in-memory Devias client with the same interface as the HTTP client. Lists its options (manifests, catalog, latency, persist, members, ai), reset, running the studio on it with VITE_MOCK=1, and testing. - [devias CLI](https://docs.devias.io/reference/cli/overview.md): The devias command previews and applies a module manifest to a workspace from a terminal or CI. Lists the five commands (plan, apply, dev, uninstall, id), the options every command takes with their environment variables, how to run it from the repository, and the API key permission it needs. - [devias plan](https://docs.devias.io/reference/cli/plan.md): devias plan lists every change applying a manifest would make, each marked create, update, delete or conflict, without writing anything. Unchanged items are hidden unless --all is passed. Exits with code 2 when the plan has conflicts and 0 otherwise. - [devias apply](https://docs.devias.io/reference/cli/apply.md): devias apply prints the plan, asks for confirmation and applies it. Flags: -y skips the question, --allow-destructive allows deletions. It refuses when the plan has conflicts, when a destructive change is not allowed, or when the workspace changed since the plan was shown. - [devias dev](https://docs.devias.io/reference/cli/dev.md): devias dev applies the manifest once, then watches the manifest folder and applies each change on save. It never applies a change that deletes data and never asks questions. Use devias apply --allow-destructive for deletions. - [devias uninstall](https://docs.devias.io/reference/cli/uninstall.md): devias uninstall shows what would be removed and asks before doing anything. Records in the module objects are removed with them, so it is destructive: --allow-destructive is required for a module that owns data. It removes only what the module owns. Core studio modules cannot be uninstalled. - [devias id](https://docs.devias.io/reference/cli/id.md): devias id [count] prints new uuids for a module manifest, one per line. The count defaults to 1 and can be up to 1,000. It works offline and needs no server, workspace or API key. Ids never change once made. - [HTTP API](https://docs.devias.io/reference/api/overview.md): How the Devias HTTP API behaves. JSON requests and responses, routes under /api/workspaces//, one permission check for every caller, every write announced as an event, and the OpenAPI document at /reference/api/openapi.json that describes all routes including module routes. - [API authentication](https://docs.devias.io/reference/api/authentication.md): How to authenticate to the Devias HTTP API. The studio uses a session cookie. Scripts, servers and the CLI use an API key sent in the x-api-key header. A key belongs to one workspace, carries a permissions map, and a call outside it is refused with FORBIDDEN. - [API errors](https://docs.devias.io/reference/api/errors.md): Every failed Devias API call returns the same JSON shape with a status code and an error object holding a stable code, a message and optional details. Lists all codes (VALIDATION, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, PLAN_MISMATCH, RATE_LIMITED and more) with their HTTP status. - [Querying records](https://docs.devias.io/reference/api/querying.md): The JSON query format for listing records through the Devias API: object, select, filter, sort, limit (default 50, up to 200), cursor, search, include and count. Lists every filter operator, how and, or and not combine conditions, and how nextCursor paging works. - [Change feed](https://docs.devias.io/reference/api/change-feed.md): How to follow every change in a Devias workspace as a server-sent events stream. Covers the ready event, ids that are per-workspace increasing sequence numbers, resuming with Last-Event-ID or ?after=, every event type, the common event fields, and which events a person may see. - [Module routes](https://docs.devias.io/reference/api/module-routes.md): How the HTTP API reaches into a module. Actions run by name at POST /api/workspaces//modules//actions/, each connection has a secret webhook address, and a module can mount its own routes under /mod// that run with the caller permissions. ## OpenAPI Specs - [openapi](/reference/api/openapi.json) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.