Quick start

Five commands take you from a fresh install to an AI agent with bounded access to your FortiGate. Everything forti keeps (profiles, credentials, certificates, plans) lives in one directory, the forti home ~/.forti, and that is also where the agent works.

Before you start

You need forti installed (Installation) and, on the FortiGate, a REST API administrator for forti with its API key. No administrator yet? The first step shows the FortiOS commands, and forti configure prints them too when you answer n to Do you have a REST API key?. The FortiOS account is the real boundary on what forti can do; see Security notes.

Create the REST API admin (if you have none)

In the FortiOS CLI. Use read-write instead of read for what forti should change (guarded or autonomous mode), and put this machine's address in the trusted host:

1config system accprofile2    edit "forti"3        set secfabgrp read4        set ftviewgrp read5        set authgrp read6        set sysgrp read7        set netgrp read8        set loggrp read9        set fwgrp read10        set vpngrp read11        set utmgrp read12        set wifi read13    next14end15config system api-user16    edit "forti"17        set accprofile "forti"18        set vdom "root"19        config trusthost20            edit 121                set ipv4-trusthost 192.0.2.5 255.255.255.25522            next23        end24    next25end26execute api-user generate-key forti

The last command shows the API key once: copy it. In the GUI: System, Administrators, Create New, REST API Admin.

2
Configure the FortiGate
```
1forti configure
```
forti asks for the address (fw.example.net, 192.0.2.1:8443 or an https URL). When the FortiGate's certificate is self-signed or a factory one, forti shows it with its fingerprint and asks whether to trust it; a yes pins that certificate, and TLS stays verified against it. Then come the API key (typed with echo off; it goes to the macOS Keychain or a 0600 file), whether to use a client certificate, and the operating mode. forti checks the connection with one read of the device. If the check fails, it keeps your answers and offers fixes, such as typing the key again or changing the address. Last, it names the profile after the device. Profiles are read-only unless you choose otherwise.
More devices later: forti configure --like fw01 starts from fw01's settings and asks only for the address and the key. See Profiles and credentials.
3
Add a client certificate (optional)
When the FortiGate should require a client certificate as well as the API key, answer y to Use a client certificate? in forti configure. forti makes the certificate in ~/.forti/certs/, issued by its own CA, prints the FortiGate commands to paste, and checks the connection once you press Enter. For more devices, choose the same certificate again from the list. Its password stays in a private file and is never printed. See Client certificates.
4
Check everything (any time)
```
1forti doctor
```
configure has just checked the connection; doctor is for later, or when something fails. It checks the forti home, file modes, the profile, that the key resolves, the TLS files (and certificates about to expire), the connection, authentication, the FortiOS version, the operating mode, and whether forti-mcp is installed. Each failure comes with the command that fixes it.
Authentication failures are never retried
FortiOS locks an API user out after repeated failures, so forti stops after one rejected attempt. A 401 does not prove the key wrong: FortiOS answers the same when this machine is not in the API user's trusted hosts. Check those first, then the key and the admin profile.
5
Set up the agent workspace
forti-mcp comes with forti:
```
1forti mcp install
```
Choose your clients (Claude Code, Codex) and the first scope, "~/.forti workspace (recommended)". forti registers the FortiGate tools in ~/.forti only, with the forti agent skill, an AGENTS.md, and rules that keep the agent away from the credentials stored there. For Codex it asks before marking ~/.forti as trusted. See AI agent integration.
6
Start the agent
```
1cd ~/.forti && claude          # or: codex
```
Claude Code asks once to approve the forti server; approve it. The agent can now discover resources, read configuration and plan changes, within the profile's mode. Agents started anywhere else do not get the FortiGate tools.

At the terminal

The same engine works directly from the shell:

1forti discover addr                                  # resources whose path contains "addr"2forti get firewall/address --fields name,subnet,comment3forti get firewall/policy --filter action==accept --fields policyid,name,srcaddr,dstaddr

A change is one command. forti shows what will change, then does what the profile's mode allows:

1forti profile mode fw01 guarded                       # read-only profiles change nothing2forti set firewall/address/LAN comment="office LAN"   # guarded: shown, then "Apply these changes? [y/N]"3forti rollback                                        # undo it4forti history                                         # what was changed, when, and who approved it

Choose the mode deliberately

read-only profiles change nothing, guarded profiles apply only a change a person approved (once, at the terminal or in the agent's chat), and autonomous profiles apply without asking. forti-mcp cannot change a mode. Read Operating modes before you pick one.

Coming from forti 0.1

An existing ~/.config/forti setup keeps working, and forti doctor points it out. Move it into ~/.forti with one command:

1forti home migrate

See Pre-0.2 setups.

Next steps

Profiles and credentials

Several FortiGates, credential sources, TLS and every forti doctor check.

Making changes

One-command changes, approvals for agents, plans, verification and rollback.

Security notes

What is stored where, and what a mode does and does not stop.

Quick start

Create the REST API admin (if you have none)

Configure the FortiGate

Add a client certificate (optional)

Check everything (any time)

Set up the agent workspace