> For the complete documentation index, see [llms.txt](https://docs.codemash.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codemash.io/cloud/files.md).

# Files

Cloud storage that participates in your backend.

> Store your project's files in your own cloud storage, with the same login, permissions, and audit trail as the rest of your project.

*Last updated 2026-09-11 · Applies to all projects*

**Where:** Files · `/projects/<project>/files`

## Why it exists

An ordinary storage bucket knows nothing about your users. It cannot say "only this customer may read this invoice", and it leaves you to write the upload and download plumbing yourself. The **Files** module puts storage behind your project's own identity and permission rules, so a file is just another thing your backend owns. The bytes still live in **your** storage account, so you keep control of the data and the bill.

## When you'd use it

* Customers upload documents (invoices, contracts, ID scans) and only the owner may download them again.
* A Database record needs attachments — a **File** field points at a file in this module.
* Your app shows user avatars or product images and needs a short-lived link instead of a public URL.

## Where to find it

Left menu → **Files**.

<figure><img src="https://760328771-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LwSkuCpTNI_AerL8J2a%2Fuploads%2Fgit-blob-d227dde3e561cbe85678db9e300fd98f919cfcad%2Ffiles.jpg?alt=media" alt=""><figcaption><p>The Files module home.</p></figcaption></figure>

## How to set it up

You need the `files:manage` permission on `files:module:all` to turn the module on, and `files:create` on `files:integration:all` to connect storage.

1. Open **Files** in the left menu. Until the module is on, the page shows an enable screen instead of the browser.
2. Press **Enable**. The module turns on and you land on the **Browser**.
3. Connect storage: go to **Integrations → Add New Integration** and pick a provider — see [Providers](/cloud/files/integrations/providers.md). Nothing can be uploaded until at least one integration exists.
4. Make one integration the **default**. New uploads go to the default.

**What "working" looks like:** the Browser shows a folder list (empty at first) instead of the "connect an integration" notice, and the **Integrations** page shows your integration with a **Default** badge.

## Good to know

* Turning the module **off** deletes the module's data inside Norbix. The file bytes in your own bucket are **not** touched.
* Folders are virtual — they are just path prefixes. A folder exists as soon as a file exists under it, and disappears when the last file is removed.
* The default integration applies per environment, so test and production can point at different buckets.
* Existing files do not move when you change the default. Only new uploads follow it.

## Screens in this module

* [Browser](/cloud/files/browser.md) — the folder tree and files, with [upload](/cloud/files/browser/upload.md) and [public links](/cloud/files/browser/public-links.md).
* [Triggers](/cloud/files/triggers.md) — run an action on `OnFileUploaded` / `OnFileDeleted`.
* [Integrations](/cloud/files/integrations.md) — where the bytes are stored, and which integration is the default.
* [Settings](/cloud/files/settings.md) — disable the module.

## Files and the AI chat

The project's AI chat can operate this module for you, and it stores its own attachments here.

**Ask it to work with files.** The chat can list your integrations, list what is in a folder, read a file's details, enable the module, and create, test, set as default, enable, disable or delete an integration. Anything destructive — adding or deleting an integration, setting a new default, turning the module off — asks you to confirm first. Useful things to say:

* "List the files under `invoices/2026`."
* "Which files integration is the default for this project?"
* "Test the production files integration."

**Where chat attachments go.** A file you attach in the chat is never kept as raw bytes in the database. When the chat session belongs to a project, the attachment is written to that project's **default files integration**, under `{accountId}/chats/{sessionId}` — so it lands in your own storage and shows up in the [Browser](/cloud/files/browser.md) like any other file. When the session is not project-scoped, it goes to the deployment's own chat store instead (a dedicated bucket on managed hosting, a volume path when self-hosted).

The integration is pinned to the attachment when it is saved, so changing the project's default integration later does not orphan older chat files.

{% hint style="info" %}
Screenshot waiting — the chat→file flow is covered by the Playwright suite (`files-chat.spec.ts`) but that spec takes no golden yet.
{% endhint %}

## Do it in code

{% tabs %}
{% tab title="JavaScript / TypeScript" %}

```ts
import { Norbix } from '@norbix.ai/ts';
const norbix = new Norbix();

await norbix.hub.files.enableFiles({});
const integrations = await norbix.hub.files.getFilesIntegrations({});
```

{% endtab %}

{% tab title=".NET" %}

```csharp
using Norbix.Sdk;

using var client = new NorbixClient();

await client.Files.EnableFilesAsync(new EnableFilesRequest());
var integrations = await client.Files.GetFilesIntegrationsAsync(new GetFilesIntegrationsRequest());
```

{% endtab %}

{% tab title="Python" %}

```python
from norbix_python import NorbixHub

norbix = NorbixHub()

norbix.files.enable_files()
integrations = norbix.files.get_files_integrations()
```

{% endtab %}

{% tab title="Go" %}

```go
c, _ := norbix.New(norbix.Options{})
ctx := context.Background()

var result map[string]any
_ = c.Hub.Files.EnableFiles(ctx, map[string]any{}, &result)
```

{% endtab %}

{% tab title="CLI" %}

```sh
norbix files list
```

{% endtab %}
{% endtabs %}

Full method list: [Files](/sdks-and-cli/files.md) — including the end-user API (upload URL, download, list own files).

## API reference

Endpoints: [Files](/api-reference/files.md).

## Related

[Browser](/cloud/files/browser.md) · [Integrations](/cloud/files/integrations.md) · [Settings](/cloud/files/settings.md) · [Database File fields](/cloud/database.md)