Local development

Develop your projects using Hosted projects in the online IDE or locally as Connected projects with the local CLI. This guide focuses on Connected projects and the local CLI. Use local development when:

You prefer your own IDE instead of Intuned’s online IDE.
You want to manage the project with version control (e.g., Git) for better collaboration and versioning.
You want to use your own development tools, extensions, and AI tools.
You prefer working in your own environment, with or without Intuned Agent (see the External agent plugin).

For the browser-based approach, see Online IDE.

Want the agent in your local setup too? Install the External agent plugin to run Intuned Agent and build, edit, and debug Connected projects locally.

Install the CLI

Install the Intuned CLI by following the CLI installation guide.

Create a project

To create a new Intuned project locally, run:

intuned dev init

npx create-intuned-project@latest

Requires Node.js and npm. Run with -h to see all available options.

The command walks you through project creation: selecting a language (TypeScript or Python), choosing a starter template, setting the project name, and connecting to your workspace. Once the project is created, you can expect the following structure:

// api
// └── ...
// auth-sessions (if AuthSessions are enabled)
// └── check.ts
// └── create.ts
// auth-sessions-instances (if AuthSessions are enabled)
// ├── test-authsession/
// └── ...
// intuned-resources
// ├── auth-sessions/ (if AuthSessions are enabled)
// │   └── test-authsession.auth-session.jsonc
// └── jobs/
//     └── default.job.jsonc
// Intuned.jsonc (Intuned settings file)
// package.json (dependencies)
// README.md
// tsconfig.json
// yarn.lock

#  api
#  └── ...
#  auth-sessions (if AuthSessions are enabled)
#  └── check.py
#  └── create.py
#  auth-sessions-instances (if AuthSessions are enabled)
#  ├── test-authsession/
#  └── ...
#  intuned-resources
#  ├── auth-sessions/ (if AuthSessions are enabled)
#  │   └── test-authsession.auth-session.jsonc
#  └── jobs/
#      └── default.job.jsonc
#  Intuned.jsonc (Intuned settings file)
#  pyproject.toml (dependencies)
#  README.md
#  uv.lock
#

Intuned settings file (Intuned.jsonc)

The Intuned settings file contains the configuration settings for your project, including AuthSessions, replication settings, and more. For local projects, this includes your workspace ID and project name. Workspace ID and project name are required to save and deploy your project to Intuned. If provided during project creation, they’re saved in the Intuned settings file automatically. Otherwise, add them manually later.

Intuned.jsonc

{
  "projectName": "<your-project-name>",
  "workspaceId": "<your-workspace-id>"
  // ...
}

Or pass them to each command as arguments. Run the respective command with -h to see the available options.

By default, the Intuned settings file is Intuned.jsonc (JSON with comments). If you want to use a different format, you can pass --settings-format <settings-format> to the create command. For more info, run with -h.

For more information on the settings file and its options, refer to Intuned settings file.

Authenticate

Authenticate to Intuned by following the CLI authentication guide. This allows you to save and deploy your project, and use CLI features that require authentication.

Local development workflow

Use any IDE or text editor to develop your project locally. Start by installing your project’s dependencies.

The recommended dependency managers are yarn (v1) for TypeScript projects and uv for Python projects.

Understand the project structure

The api directory contains your browser automation APIs. Create new APIs by adding new files in this directory, which can be nested. An example for a social media RPA project:

// api/
// ├── messages/
// │   ├── send.ts
// │   └── react.ts
// └── posts/
//     ├── react.ts
//     ├── reply.ts
//     └── share.ts

// Available APIs:
//  messages/send
//  messages/react
//  posts/react
//  posts/reply
//  posts/share

#  api/
#  ├── messages/
#  │   ├── send.py
#  │   └── react.py
#  └── posts/
#      ├── react.py
#      ├── reply.py
#      └── share.py
#
#  Available APIs:
#   messages/send
#   messages/react
#   posts/react
#   posts/reply
#   posts/share

Write APIs

Implement your APIs using any functions, classes, or design patterns you prefer. The entry point for each API is defined as follows:

api/example.ts

// The default export is the entry point for the API

export default async function automation(
  params: any,
  page: Page,
  context: BrowserContext
) {
  // Your automation code here
  return {}; // Return results
}

# The function named `automation` is the entry point for the API

async def automation(
    page: Page,
    params: Any | None = None,
    **kwargs
):
    # Your automation code here
    return {} # Return results

Define other directories and files to import from and use in your APIs as needed.

Run APIs

Run an API:

Run with -h or check out CLI Reference to see all available options.

Debug APIs

If the API isn’t running as expected, use the --keep-browser-open flag to keep the browser open for debugging. Use the --trace flag to generate a trace, which you can open with Playwright’s trace viewer. Open the trace with:

npx playwright show-trace <trace-file>

Work with AuthSessions

AuthSessions are reusable authentication sessions shared across multiple APIs. They manage authentication flows and store session data securely. For more information, refer to AuthSessions (authenticated automation).

If you use a starter template that includes AuthSessions, the project comes with an AuthSession instance called test-authsession that you can find under the auth-sessions-instances directory.

AuthSession directories

During local development, projects using AuthSessions have two additional directories:

auth-sessions: Contains the create and check functions for AuthSessions.
auth-session-instances: Contains the stored AuthSession instances. Each instance is stored in a separate directory with its ID as the directory name.

The auth-session-instances directory is only used during local development. When deployed, AuthSession data is stored securely and encrypted on Intuned’s infrastructure.

// auth-sessions/
// ├── create.ts
// └── check.ts
// auth-session-instances/
// ├── test-authsession/ # test-authsession is an id for an AuthSession
// └── auth-session-2/    # auth-session-2 is an id for an AuthSession

# auth-sessions/
# ├── create.py
# └── check.py
# auth-session-instances/
# ├── test-authsession/ # test-authsession is an id for an AuthSession
# └── auth-session-2/    # auth-session-2 is an id for an AuthSession

Write the create function

Inside auth-sessions/create, write code that creates your AuthSession (e.g., logging in). The create function doesn’t return anything—the browser state is captured after it completes.

auth-sessions/create.ts

export default async function create(
  page: Page,
  params: any,
  context: BrowserContext
) {
  // Your authentication code here
}

async def create(
    page: Page,
    params: Any | None = None,
    **kwargs
):
    # Your authentication code here
    ...

Write the check function

Inside auth-sessions/check, write code to verify the AuthSession is valid (e.g., checking the profile page to confirm you’re logged in). The check function takes no parameters and returns a boolean indicating whether the session is valid.

auth-sessions/check.ts

export default async function check(
  page: Page,
  context: BrowserContext
): Promise<boolean> {
  // Your session validation code here
  return true; // Return true if valid, false otherwise. Error will also be treated as invalid.
}

async def check(
    page: Page,
    **kwargs
) -> bool:
    # Your session validation code here
    return True  # Return True if valid, False otherwise. Exception will also be treated as invalid.

Manage AuthSessions

Create an AuthSession: Validate an AuthSession: Update an existing AuthSession:

Run with -h or check out the CLI Reference to see all available options.

Run APIs with AuthSessions

When AuthSessions are enabled, APIs require an AuthSession ID to run:

Use Runtime SDK and browser SDK helpers

Some helpers in the Intuned Runtime SDK and Browser SDK need backend resources that are only available after you provision your project. Without provisioning, you’ll see one of these messages:

Unauthorized backend function call - make sure to provision your project to Intuned to set up the correct API credentials

API credentials not set - make sure to provision your project to Intuned to set up the correct API credentials.

Resolve this by provisioning the project, then saving its local files:

If you don’t have your project name and workspace ID set in the Intuned settings file, provide them as arguments/options.

Deploy your project

When your project is ready, deploy it. The command saves local changes before starting the deployment: After deployment succeeds, follow the output links for next steps. Use --no-save only when the current project on Intuned is already the version you want to deploy. If a save needs confirmation in automation, the command aborts unless you explicitly pass --override.

If you don’t have your project name and workspace ID set in the Intuned settings file, provide them as arguments/options.

Set up CI/CD

Integrate Intuned deployment into your CI/CD pipelines with the CLI. Set INTUNED_API_KEY in your CI/CD environment.

name: Deploy to Intuned
on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '24'
      - name: Install Intuned CLI
        run: npm install -g @intuned/cli
      - name: Install dependencies
        run: yarn install
      - name: Deploy to Intuned
        env:
          INTUNED_API_KEY: ${{ secrets.INTUNED_API_KEY }}
        run: intuned dev deploy --non-interactive --override

name: Deploy to Intuned
on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Node.js
        uses: actions/setup-node@v2
        with:
          node-version: "24"
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install uv
        run: pip install uv
      - name: Install Intuned CLI
        run: npm install -g @intuned/cli
      - name: Install dependencies
        run: uv sync
      - name: Deploy to Intuned
        env:
          INTUNED_API_KEY: ${{ secrets.INTUNED_API_KEY }}
        run: intuned dev deploy --non-interactive --override

When to use Hosted projects (online IDE) vs Connected projects (local CLI)

Feature	Hosted projects (online IDE)	Connected projects (local CLI)
Setup	Zero setup, browser-based	Requires Python or Node runtime and Intuned CLI
Use case	Use Intuned Agent to build and edit scrapers Use platform-specific features like stealth and captcha solving Quick prototyping	Integrating your own CI/CD with version control and predefined team workflows
Platform AI	Full access to platform AI features like Fix with AI, Fix issues, and self-healing projects	Platform AI features like Fix with AI, Fix issues, and self-healing projects are not supported
Intuned Agent	Build and edit in the online IDE or a full agent session	Run the agent locally with the External agent plugin (Claude Code, Codex)
Version control	No Git integration Use built-in deployment tracking and history management	Full Git workflow that works with your team and your own repo
Collaboration	Single developer (no concurrent editing)	Multiple developers with version control
IDE choice	Intuned’s web-based editor	Use your preferred IDE (VS Code, JetBrains, etc.)

CLI reference

Complete CLI command documentation

How the platform works

Understand Intuned’s architecture and execution model

AuthSessions

Build authenticated automations

Online IDE

Build automations with zero setup

Getting started

Intuned Agent

Web Tasks

Platform features

Learn

How-To

Integrations

References

Resources

Local development

Install the CLI

Create a project

Intuned settings file (Intuned.jsonc)

Authenticate

Local development workflow

Understand the project structure

Write APIs

Run APIs

Debug APIs

Work with AuthSessions

AuthSession directories

Write the create function

Write the check function

Manage AuthSessions

Run APIs with AuthSessions

Use Runtime SDK and browser SDK helpers

Deploy your project

Set up CI/CD

When to use Hosted projects (online IDE) vs Connected projects (local CLI)

CLI reference

How the platform works

AuthSessions

Online IDE

​Install the CLI

​Create a project

​Intuned settings file (Intuned.jsonc)

​Authenticate

​Local development workflow

​Understand the project structure

​Write APIs

​Run APIs

​Debug APIs

​Work with AuthSessions

​AuthSession directories

​Write the create function

​Write the check function

​Manage AuthSessions

​Run APIs with AuthSessions

​Use Runtime SDK and browser SDK helpers

​Deploy your project

​Set up CI/CD

​When to use Hosted projects (online IDE) vs Connected projects (local CLI)

​Related resources

CLI reference

How the platform works

AuthSessions

Online IDE

Install the CLI

Create a project

Intuned settings file (Intuned.jsonc)

Authenticate

Local development workflow

Understand the project structure

Write APIs

Run APIs

Debug APIs

Work with AuthSessions

AuthSession directories

Write the create function

Write the check function

Manage AuthSessions

Run APIs with AuthSessions

Use Runtime SDK and browser SDK helpers

Deploy your project

Set up CI/CD

When to use Hosted projects (online IDE) vs Connected projects (local CLI)

Related resources