This page walks through building a module with a coding agent such as Claude Code, Cursor or Claude, from the first idea to a Marketplace listing: what to ask the agent, the connector tool it uses and the matching dv command.
You need to be a Workspace Admin. Only admins get the module-building tools.
A prompt to start with
Paste this into your coding agent once the connector is set up:
To change a module you already have, name it instead: "Check out our Tool Calibration module and add a due-date reminder."
1. Connect
Add the connector to your agent with your workspace's connector address (System settings > Marketplace > Connect your AI > Copy). See The Data Visions connector (MCP).
For the agent to deploy or check in, three things must allow it: your workspace's AI connectors setting must be Read and make changes, you must allow changes when you connect, and your role must be Workspace Admin. See Security: AI connectors.
Agents with a terminal can also use the CLI: ask the agent to set it up (it uses the connector's cli_setup tool). See Install and sign in to the CLI.
2. Read the SDK
Ask: "Read the Module SDK before you start." The agent calls sdk_doc with no path for the index, then reads skills/starting-a-module/SKILL.md and SKILL.md. See The Module SDK.
3. Plan a new module, or check out an existing one
A new module. The starting-a-module guide has the agent coach you before it builds:
- What problem you want solved, who uses it, and how it is done today. Share an example sheet or form if you have one.
- What the platform already gives you (dashboards, forms, file storage, an AI agent, schedules, roles), so it isn't rebuilt.
- A short plan: screens, tables, who can do what, reports, and what to leave for later.
No files until you agree the plan. Keep version 1 small enough to deploy the same day. If the module code it wanted is taken (the module list includes other publishers' Marketplace modules), it picks another.
An existing module. Ask: "Check out our module." The agent calls checkout_module, which returns the latest code and the base a check-in must name. With the CLI, dv modules checkout <code> puts the code in a new folder. You can check out only modules your workspace owns, not Marketplace modules.
4. Build it
A module is one folder named after its module code in lower case:
| File or folder | What it holds |
|---|---|
module.json | The manifest: identity, version, permissions, tables, agent, screens. See Module manifest (module.json) reference. |
api.py | The module's web routes. Every route requires a permission. |
service.py | Business logic, reading and writing the module's own tables. |
schemas.py | The shapes of requests and responses. |
services.py | Services the module offers other modules, and scheduled jobs. |
ai/tools.py | Tools for the module's AI agent. |
ai/skills/ | Skills for the agent, dataset packages for dashboards, and report templates. |
ui/ | The pages, including the required icon (ui/icon.svg) and an optional settings page. |
qa/procedures.json | Who uses the module and what to test. Required for the Marketplace. |
tests/ | Tests that run without the platform or a database. |
module.json, api.py, service.py and schemas.py are required. The agent usually starts from the SDK's example module, examples/assets/, under a new module code, and builds in small steps.
5. Validate
Ask: "Validate the module." The agent calls validate_module, or runs dv modules validate <folder>. This runs the quick, automatic checks without deploying. Each finding says what is wrong, why and how to fix it.
Recommendations are your decision, such as whether to publish the module's data to dashboards. The agent should ask you, never decide for you.
With the CLI installed, the agent can also run the module's tests with pytest, and the security scanners with dv modules scan <folder>.
6. Run the module check
Ask: "Run the module check." The agent calls review_module, or runs dv modules review <folder>. This is the same check every deploy must pass: the validator, the security scanner, known-vulnerable libraries and an AI code review. It takes a minute or more.
It returns a must-fix list and a count of advisories that don't block. Fix every must-fix item and run it again; deploying the same files reuses the result. dv modules rules shows the rules the AI review applies. A finding that truly doesn't apply can be appealed to Data Visions staff with escalate_module_review (or dv modules escalate <sha256> --reason "..."). See Publish a module: the module check.
7. Deploy to your own workspace
Ask: "Deploy it to our workspace." The agent should ask you first, then call deploy_module, or run dv modules deploy <folder>.
The first deploy needs a subscribe. Deploying registers the module in your workspace; subscribing turns it on, creates its tables, adds its permissions to roles and puts it in the sidebar.
- Connector:
deploy_modulewithsubscribeset to true. - CLI:
dv modules deploy <folder> --subscribe <your-workspace-slug>.dv dev statusshows the slug.
Later versions deploy without the subscribe. A deploy can take a few minutes while your workspace's sandbox restarts with the new code. You can deploy only to your own workspace.
Through the connector, a module can be up to about 8 MB or 400 files. Deploy larger ones with the CLI.
Check in or deploy?
| Check in | Deploy | |
|---|---|---|
| Tool | checkin_module, or dv modules checkin | deploy_module, or dv modules deploy |
| Goes live | No. It becomes the next revision of the module's draft. | Yes, for your workspace. |
| Next step | A Workspace Admin previews and publishes it in the Module Builder. | Open it from the sidebar. |
| Use when | Others are working on the same module, or someone should look before it goes live. | You own the change and want it running. |
A check-in names the base it started from. If someone else checked in or published first, it is refused: the agent checks out again (or runs dv modules pull), redoes its change on the new code and checks in again. See Several people changing one module.
8. Try it
Every module runs in your workspace's own sandbox. Open it from the sidebar and use it the way your people will. If a page is missing or a tool says Permission denied, give yourself a role that holds the module's permissions in Users and roles.
With the CLI, dv modules preview <code> opens the module in your browser.
9. Read the logs
When something fails, ask: "Show me the module's logs." The agent calls module_logs, which returns the latest lines from your workspace's sandbox (200 by default, up to 1,000). Pass the module code to keep only lines that mention it. With the CLI: dv sandbox logs -n 200.
10. Versions
Ask: "What versions of this module do we have?" The agent calls module_versions, which lists the versions your workspace can see, which one is installed, and the install and update history. With the CLI: dv modules versions <code>, and dv modules update <code> moves your install to the newest version. See Versions, drafts and history.
11. Raise the version for every change
Versions can't be changed once deployed. Before deploying changed files, raise version in module.json (for example 0.1.0 to 0.2.0). Changed code under an existing version is refused, and a version lower than the live one is refused. Deploying the exact same files again is harmless.
Tables only grow: new columns and tables are added, nothing is dropped or renamed, and existing data is reshaped with data_migrations. See Module manifest (module.json) reference.
12. Submit to the Marketplace
If other companies could use the module, ask: "Submit it to the Marketplace." The agent should ask you first, then call submit_to_marketplace, or run dv modules publish <code> -m "what changed". It submits the latest deployed version.
Before it will be accepted, the module needs:
"distribution": {"visibility": "marketplace", ...}inmodule.json.- QA procedures in
qa/procedures.json(thewriting-qa-proceduresskill). - At least one dataset for dashboards (the
registering-datasetsskill).
A refusal lists each blocking item with its fix: fix, raise the version, deploy and submit again. Data Visions staff test the module against its QA procedures and approve or reject it. Follow along with marketplace_status or dv modules publish-status.
Good to know
- Ask before deploying. The agent should confirm with you before every deploy and Marketplace submission.
- Module codes are permanent. Pick one you can live with; changing it later means a new module.
- Marketplace modules can't be checked out. Their code belongs to their publisher.
- For every tool and command in detail, see Connector tool reference and CLI command reference.