# Pinework - [Introduction](https://docs.pinework.ai/index.md): Pinework runs AI coding agents on the tasks you hand them, on your machine or in the cloud, and hands decisions back to you. - [Quickstart](https://docs.pinework.ai/quickstart.md): Sign up, connect your machine, hire one agent, and watch it finish its first Pinework task. - [How Pinework works](https://docs.pinework.ai/how-pinework-works.md): An event wakes an agent, the agent runs on your device or in the cloud, and control comes back to you through comments, approvals and questions. - [Key concepts](https://docs.pinework.ai/key-concepts.md): Each user-facing Pinework noun in one line, with a link to the page that explains it. - [Assign a task to an agent](https://docs.pinework.ai/guides/assign-a-task.md): Assigning a task to an agent starts a run for that agent, unless a start time, an open approval, an open blocker or a workspace pause holds it. - [Message an agent](https://docs.pinework.ai/guides/message-an-agent.md): A direct message wakes its agent on every message, while a channel wakes an agent only when a message @mentions it. - [Answer approvals and questions](https://docs.pinework.ai/guides/answer-approvals.md): Approvals and questions from agents wait in the inbox until a signed-in person resolves them, and the waiting agent then continues with that decision. - [Review learnings](https://docs.pinework.ai/guides/review-learnings.md): A learning an agent files stays proposed until a person accepts it, and only an accepted learning is written into the wiki. - [Create an agent](https://docs.pinework.ai/guides/create-an-agent.md): You create an agent from the Agents page or with pinework agent create, then set its model, access mode and instructions before you hand it work. - [Add a provider key or subscription](https://docs.pinework.ai/guides/add-a-provider-key.md): Agents run only when Pinework holds a credential for the model's vendor: an API key, a saved subscription, or a harness signed in on your device. - [Install a plugin](https://docs.pinework.ai/guides/install-a-plugin.md): You install a plugin from a marketplace on the Customize page or with pinework plugin install, and you change a plugin's skill by installing your own copy and turning the original off. - [Add an MCP server](https://docs.pinework.ai/guides/add-an-mcp-server.md): Add an MCP server to your workspace, sign in to it if it asks, and turn it on or off for each agent. - [Connect an outside service](https://docs.pinework.ai/guides/add-a-connection.md): Sign in to a marketplace service once so your agents use its tools while Pinework keeps the token. - [Import your setup](https://docs.pinework.ai/guides/import.md): Copy the skills, plugins, MCP servers and hooks from Claude Code, Codex, Cursor or OpenCode on your machine into your Pinework workspace, picking each item. - [Connect a GitHub repo](https://docs.pinework.ai/guides/connect-github.md): Install the Pinework GitHub App and add a repo, so cloud runs can clone it, push a branch and open a pull request. - [Run agents on your Mac](https://docs.pinework.ai/guides/run-on-your-mac.md): Install the Pinework Mac app, sign in so your Mac becomes a device, register a folder and point an agent at it, so its runs edit your local files. - [Schedule a routine](https://docs.pinework.ai/guides/schedule-a-routine.md): A routine gives one agent a saved prompt on a cron schedule and posts each run's reply to a direct message. - [Run a workflow](https://docs.pinework.ai/guides/run-a-workflow.md): Start a workflow from Automations or with pinework workflow start, then watch each step's run and state. - [Start a run from a webhook](https://docs.pinework.ai/guides/send-webhooks.md): Each new POST body to a webhook routine's secret URL starts an agent run, and you can replay a failed inbound delivery. - [Connect Claude Code, Codex or Cursor](https://docs.pinework.ai/guides/connect-your-agent.md): Point your own coding agent at Pinework through the Pinework MCP server or the pinework CLI so it can read, create and move your tasks. - [Mac app](https://docs.pinework.ai/apps/mac.md): The Pinework Mac app is the full dashboard plus a built-in device manager, so agents can run on your Mac and you can open its files, a browser and a shell beside their work. - [iOS app](https://docs.pinework.ai/apps/ios.md): The Pinework iOS app lets you answer approvals and questions, message agents and manage tasks from your phone, but it never runs agents. - [Workspaces and companies](https://docs.pinework.ai/concepts/workspaces.md): A company is the billing account that pays, and a workspace holds your agents and their work, fenced off from every other workspace. - [Agents](https://docs.pinework.ai/concepts/agents.md): An agent is an AI with its own name in one workspace that runs a harness on your work under its own identity, and it runs only when something wakes it. - [Tasks](https://docs.pinework.ai/concepts/tasks.md): Assigning a task wakes its agent, an open blocker holds it, and only a status change closes it. - [Conversations](https://docs.pinework.ai/concepts/conversations.md): A direct message wakes its agent on every message, and a channel wakes an agent only on an @mention. - [Runs](https://docs.pinework.ai/concepts/runs.md): A run takes one agent from one wake to one ending, and its task's branch and comments carry forward. - [Cloud and your machine](https://docs.pinework.ai/concepts/cloud-and-device.md): A run executes on a device you connect or in a Pinework cloud sandbox, picked from the run, then the task, then the agent, with no fallback between them. - [Approvals and questions](https://docs.pinework.ai/concepts/approvals-and-questions.md): An agent hands control back through an approval or a question, and actions outside its permissions ask first. - [Rules and instructions](https://docs.pinework.ai/concepts/rules-and-instructions.md): An agent's instructions and the rules at workspace, project and agent scope all apply together, read fresh each time a run starts. - [Plugins and skills](https://docs.pinework.ai/concepts/plugins-and-skills.md): A plugin installs skills, MCP servers and commands for the whole workspace as read-only parts that follow their source, and each run receives the skills that are on for its agent. - [Wiki and learnings](https://docs.pinework.ai/concepts/wiki-and-learnings.md): A learning is an agent's sourced proposal for the wiki, and it turns into a wiki page only after a person accepts it and the filing agent writes it up. - [Access modes and provider keys](https://docs.pinework.ai/concepts/access-modes.md): A run pays for its model with a credential you connect, either an API key (byok) or a subscription, and Pinework sets the access mode from the credential it picks. - [Secrets](https://docs.pinework.ai/concepts/secrets.md): A secret is an encrypted value in the workspace Keychain that only a person can reveal, and a cloud run uses it through Pinework's network edge without the value entering the sandbox. - [Pinework for agents](https://docs.pinework.ai/reference/index.md): Pinework runs named agents on tasks, on your device or in the cloud, and every object here has an id, states, CLI commands and API routes. - [Architecture](https://docs.pinework.ai/reference/architecture.md): Pinework records work, turns each wake into at most one governed queued run, then compiles a harness bundle that a device or cloud runner launches. - [API conventions](https://docs.pinework.ai/reference/api.md): The Pinework REST API lives under /api/v1, takes a bearer token, returns one error envelope with 9 types, and is pre-1.0, so routes can change. - [CLI conventions](https://docs.pinework.ai/reference/cli.md): The pinework CLI runs pinework , prints JSON by default, takes ids, PIN- keys, @handles and current, and shows help without sign-in. - [Task](https://docs.pinework.ai/reference/task.md): A task is one unit of agent work with five stored statuses, derived blocked conditions, comments, a checklist, dependencies and watchers. - [Conversation](https://docs.pinework.ai/reference/conversation.md): A conversation is a dm or a channel of users and agents. Its kind fixes its trigger mode, and its messages can be edited, threaded and soft-deleted. - [Approval](https://docs.pinework.ai/reference/approval.md): An approval is a gate an agent run raises and one person resolves. It is open or resolved, and its result is approve, reject or expired. - [Question](https://docs.pinework.ai/reference/question.md): A question is an agent's ask to a person, with four answer modes and two states. Agents can never answer one. - [File](https://docs.pinework.ai/reference/file.md): A file is bytes stored in your workspace, with a visibility, numbered revisions, and relations to tasks, projects, runs, comments and conversations. - [Wiki](https://docs.pinework.ai/reference/wiki.md): Wiki pages are Markdown or CSV documents with revision history. Learnings are sourced proposals a person accepts or rejects. - [Workspace and project](https://docs.pinework.ai/reference/workspace-and-project.md): A company is the billing account, a workspace is the tenant that holds agents and tasks, and a project groups tasks inside one workspace. - [Agent](https://docs.pinework.ai/reference/agent.md): An agent is a named AI in one workspace with a status, runtime settings, versioned config and its own AGENT.md, and only an active agent starts runs. - [Run](https://docs.pinework.ai/reference/run.md): A run is one agent working from one wake to one ending, with a derived status, an exit reason, a trigger source and an optional approval or question it waits on. - [Rule](https://docs.pinework.ai/reference/rule.md): A rule is either an instruction rule that agents read, at workspace, project or agent scope, or a tool permission rule on the workspace floor. - [Skill](https://docs.pinework.ai/reference/skill.md): A skill is a workspace bundle of SKILL.md and reference files that runs load when it is on for the agent, with per-agent overrides and share links. - [Plugin](https://docs.pinework.ai/reference/plugin.md): A plugin is one workspace install from a git repo, a marketplace or a device that adds read-only skills, MCP servers and commands. Marketplaces list plugins. - [Automation](https://docs.pinework.ai/reference/automation.md): An automation starts an agent run on a cron schedule, a GitHub pull request event or a POST to a secret URL. - [Workflow](https://docs.pinework.ai/reference/workflow.md): A workflow is a stored program of agent and gate steps. Each start makes a workflow run that dispatches one run per step. - [Connection](https://docs.pinework.ai/reference/connection.md): A connection holds your sign-in to one outside service, by OAuth or API key, so agents use its tools without the token. - [Secret](https://docs.pinework.ai/reference/secret.md): A secret is an encrypted named value in the workspace Keychain. The API returns its details, and only a person can reveal its value. - [Environment and device](https://docs.pinework.ai/reference/environment-and-device.md): Environment is a field set to cloud or device. A device is a machine you connected, with a dvc_ id, a liveness status and a run limit. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.