> ## Documentation Index
> Fetch the complete documentation index at: https://help.iteam.works/llms.txt
> Use this file to discover all available pages before exploring further.

# Codes — project code

> Codes are Python or Node scripts that run inside your project, in an isolated sandbox. This page covers the three types (job, service, and artifact), how a Code reaches data without credentials, and how agents call your Code.

**Codes** are pieces of code that live inside a project. You write them in your IDE, version them in Git, and iTeam runs them in an **isolated, ephemeral sandbox** — no server to maintain, no credentials in the code.

<Frame caption="📸 Screenshot to insert [/en/projects/codes]: the Codes tab of a project showing the project token, the data resources, and the list of Codes with the Run now button.">
  <img src="https://mintcdn.com/iteam/E1mg8rFlXblsaNT0/images/placeholder.svg?fit=max&auto=format&n=E1mg8rFlXblsaNT0&q=85&s=36c435f4df28c31a7e114586a931bbd2" alt="The Codes tab of a project" width="800" height="420" data-path="images/placeholder.svg" />
</Frame>

## The three types

<CardGroup cols={3}>
  <Card title="Job" icon="play">
    Code that **runs and finishes**. Use it for ETL, a daily report, an import, a cleanup. It can be scheduled.
  </Card>

  <Card title="Service" icon="server">
    An **HTTP API** with one or more endpoints. It stays up and answers calls — yours or another system's.
  </Card>

  <Card title="Artifact" icon="layout-dashboard">
    **React screens** using the iTeam design system. They consume your API and become a real interface inside the platform.
  </Card>
</CardGroup>

## Data without credentials in the code

This is the part that changes how you write. A Code **never** carries a database address or a password: it asks for the resource and the server resolves it.

<AccordionGroup>
  <Accordion title="Data Store (ClickHouse)" icon="database">
    Analytical and columnar — built for aggregation and volume. Use `datastore.query(sql)`.

    Every project gets **its own database**, isolated from the rest. A Code never sees another project's Data Store.
  </Accordion>

  <Accordion title="Database (Postgres)" icon="table">
    Relational, read and write, with `db.query(sql)` and `db.execute(sql)`. Also isolated per project.
  </Accordion>

  <Accordion title="Agent resources (inherited)" icon="share-2">
    Add **agents to the project** and your Code can use their tools — MCPs, APIs, HTTP tools, and data sources — through `agent_tools()`.

    Secrets stay in the vault and are resolved server-side. **Remove the agent from the project and the Code loses access immediately.**
  </Accordion>
</AccordionGroup>

<Tip>
  Call `resources()` at the start of your Code to discover what that project offers. Your IDE picks everything up automatically — the name and schema of each tool.
</Tip>

## The project token

Deploys happen over the API with a **project token** (`pct_...`). You'll find it in the Codes tab, with actions to **copy**, **rotate**, and **revoke**.

<Warning>
  The token grants write access to your project. Keep it in `.env` and **never** in Git. If it leaks, hit **Rotate** — the old one stops working immediately.
</Warning>

## Scheduling

A job can run on its own, at a fixed time, using cron notation:

```
0 6 * * *     every day at 06:00
*/15 * * * *  every 15 minutes
0 8 * * 1     every Monday at 08:00
```

You can also trigger it right away with **Run now**, and follow the run history with status, duration, and output.

## Agents calling your Code

A Code published with a **contract** (declared input and output) becomes a tool the project's agents can call on their own.

<Steps>
  <Step title="Declare the contract">
    Define what the Code takes and what it returns. That's what the agent sees.
  </Step>

  <Step title="Publish">
    A published Code shows up as callable in the list.
  </Step>

  <Step title="The agent uses it">
    In a conversation, the agent decides to call your Code when the question calls for it — and uses the result in its answer.
  </Step>
</Steps>

## Pick up where you left off

Code is versioned in the platform's Git. Before touching an existing Code, run **pull** — so you continue instead of recreating.

<Info>
  `pull` brings the entry file **and** the Code's extra files. It's the reliable way to get a faithful local copy.
</Info>

## Good practices

<CardGroup cols={2}>
  <Card title="Make the job idempotent" icon="repeat">
    Delete the period before writing it. That way re-running the same day fixes instead of duplicating.
  </Card>

  <Card title="Aggregate at the source" icon="filter">
    `GROUP BY` in the query beats pulling thousands of rows into the Code.
  </Card>

  <Card title="Fail with a clear message" icon="triangle-alert">
    An error output explaining what was missing beats a stack trace in the history.
  </Card>

  <Card title="Accept a date parameter" icon="calendar">
    A job that only knows how to process "today" can't backfill a missed day. Taking a date fixes that.
  </Card>
</CardGroup>
